qiskit_superstaq package

Submodules

qiskit_superstaq.compiler_output module

class qiskit_superstaq.compiler_output.CompilerOutput(circuits: qiskit.QuantumCircuit | List[qiskit.QuantumCircuit] | List[List[qiskit.QuantumCircuit]], final_logical_to_physicals: Dict[int, int] | List[Dict[int, int]] | List[List[Dict[int, int]]], pulse_gate_circuits: qiskit.QuantumCircuit | List[qiskit.QuantumCircuit] = None, pulse_sequences: qiskit.pulse.Schedule | List[qiskit.pulse.Schedule] | None = None, seq: qtrl.sequencer.Sequence | None = None, jaqal_programs: str | List[str] | None = None, pulse_lists: List[List[List[Any]]] | List[List[List[List[Any]]]] | None = None)

Bases: object

A class that stores the results of compiled circuits.

has_multiple_circuits() → bool

Checks if this object represents multiple circuits.

If so, this object has .circuits and .pulse_lists attributes. Otherwise, this object represents a single circuit, and has .circuit and .pulse_list attributes.

Returns:

A boolean indicating whether this object represents multiple circuits.

qiskit_superstaq.compiler_output.active_qubit_indices(circuit: QuantumCircuit) → List[int]

Returns the indices of the non-idle qubits in the input quantum circuit.

Parameters:

circuit – A qiskit.QuantumCircuit circuit.

Returns:

A list containing the indices of the non-idle qubits.

qiskit_superstaq.compiler_output.measured_qubit_indices(circuit: QuantumCircuit) → List[int]

Returns the indices of the measured qubits in the input quantum circuit.

Parameters:

circuit – A qiskit.QuantumCircuit circuit.

Returns:

A list containing the indices of the measured qubits.

qiskit_superstaq.compiler_output.read_json(json_dict: Dict[str, str], circuits_is_list: bool) → CompilerOutput

Reads out returned JSON from Superstaq API’s compilation endpoints.

Parameters:

  • json_dict – A JSON dictionary matching the format returned by /compile endpoint.

  • circuits_is_list – A bool flag that controls whether the returned object has a .circuits attribute (if True) or a .circuit attribute (False).

Returns:

A CompilerOutput object with the compiled circuit(s) and (if applicable to this target) corresponding pulse gate circuit(s).

qiskit_superstaq.compiler_output.read_json_aqt(json_dict: Dict[str, str], circuits_is_list: bool, num_eca_circuits: int | None = None) → CompilerOutput

Reads out the returned JSON from Superstaq API’s AQT compilation endpoint.

Parameters:

  • json_dict – A JSON dictionary matching the format returned by /aqt_compile endpoint.

  • circuits_is_list – Bool flag that controls whether the returned object has a .circuits attribute (if True) or a .circuit attribute (False).

  • num_eca_circuits – Optional number of logically equivalent random circuits to generate for each input circuit.

Returns:

A CompilerOutput object with the compiled circuit(s). If qtrl is available locally, the returned object also stores the pulse sequence in the .seq attribute and the list(s) of cycles in the .pulse_list(s) attribute.

qiskit_superstaq.compiler_output.read_json_qscout(json_dict: Dict[str, str | List[str]], circuits_is_list: bool) → CompilerOutput

Reads out the returned JSON from Superstaq API’s QSCOUT compilation endpoint.

Parameters:

  • json_dict – A JSON dictionary matching the format returned by /qscout_compile endpoint.

  • circuits_is_list – Bool flag that controls whether the returned object has a .circuits attribute (if True) or a .circuit attribute (False).

Returns:

A CompilerOutput object with the compiled circuit(s) and a list of jaqal programs in a string representation.

qiskit_superstaq.custom_gates module

class qiskit_superstaq.custom_gates.AQTiCCXGate(label: str | None = None)

Bases: iCCXGate

A subclass of the iCCXGate for AQT where the control state is “00”.

qiskit_superstaq.custom_gates.AQTiToffoliGate

alias of AQTiCCXGate

class qiskit_superstaq.custom_gates.AceCR(rads: str | float = 1.5707963267948966, sandwich_rx_rads: float = 0, label: str | None = None)

Bases: Gate

Active Cancellation Echoed Cross Resonance gate, supporting polarity switches and sandwiches.

The typical AceCR in the literature is a positive half-CR, then X on “Z side”, then negative half-CR (where “Z side” and “X side” refer to the two sides of the underlying ZX interactions).

inverse() → AceCR

Inverts the AceCR gate.

Returns:

The inverse AceCR gate.

class qiskit_superstaq.custom_gates.ParallelGates(*component_gates: Gate, label: str | None = None)

Bases: Gate

A single gate combining a collection of concurrent gate(s) acting on different qubits.

inverse() → ParallelGates

Inverts parallel gates.

Returns:

The inverse parallel gates.

class qiskit_superstaq.custom_gates.StrippedCZGate(rz_rads: float)

Bases: Gate

The Stripped CZ gate is a regular CZ gate when the rz angle = 0.

It is the gate that is actually being performed by Hilbert, and it is corrected into a CZ gate by RZ gates afterwards if the rz angle is nonzero.

inverse() → StrippedCZGate

Inverts the stripped CZ gate.

Returns:

The inverse Stripped CZ gate.

class qiskit_superstaq.custom_gates.ZZSwapGate(theta: float, label: str | None = None)

Bases: Gate

The ZZ-SWAP gate, which performs the ZZ-interaction followed by a SWAP.

ZZ-SWAPs are useful for applications like QAOA or Hamiltonian Simulation, particularly on linear- or low- connectivity devices. See https://arxiv.org/pdf/2004.14970.pdf for an application of ZZ-SWAP networks.

The unitary for a ZZ-SWAP gate parametrized by ZZ-interaction angle \(\theta\) is:

\[\begin{split}\begin{bmatrix} 1 & . & . & . \\ . & . & e^{i \theta} & . \\ . & e^{i \theta} & . & . \\ . & . & . & 1 \\ \end{bmatrix}\end{split}\]

where ‘.’ means ‘0’. For \(\theta = 0\), the ZZ-SWAP gate is just an ordinary SWAP.

inverse() → ZZSwapGate

Inverts the ZZ-SWAP gate.

Returns:

The inverse ZZ-SWAP gate.

qiskit_superstaq.custom_gates.custom_resolver(gate: Instruction) → Gate | None

Recovers a custom gate type from a generic qiskit.circuit.Gate.

The resolution is done using gate.definition.name rather than gate.name, as the former is set by all qiskit-superstaq custom gates and the latter may be modified by calls such as qiskit.QuantumCircuit.qasm().

Parameters:

gate – The input gate instruction from which to recover a custom gate type.

Returns:

A qiskit.circuit.Gate if the gate definition name is in the _custom_gate_resolver dictionary (or the definition name is “parallel_gates”).

class qiskit_superstaq.custom_gates.iCCXGate(label: str | None = None, ctrl_state: str | int | None = None)

Bases: ControlledGate

An iCCX gate which consists of a Toffoli gate and a subsequent controlled phase gate.

The two qubit controlled phase gate uses an angle of rotation of \(\frac{\pi}{2}\) on the second qubit with the first qubit acting as the control. That is, it is a composite gate of the following instructions:

q_0: ──■───■───────
       │   │P(π/2)
q_1: ──■───■───────
     ┌─┴─┐
q_2: ┤ X ├─────────
     └───┘
class qiskit_superstaq.custom_gates.iCCXdgGate(label: str | None = None, ctrl_state: str | int | None = None)

Bases: ControlledGate

The conjugate transpose of the iCCXGate (\(iCCXGate^{\dagger} = iCCXdgGate\)).

class qiskit_superstaq.custom_gates.iXGate(label: str | None = None)

Bases: Gate

The iX gate (a single qubit Pauli-X gate with a global phase of i).

It is a special case of when the RX gate’s input rotation angle is \(-\pi\):

\[\begin{split}\begin{bmatrix} 0 & i \\ i & 0 \\ \end{bmatrix}\end{split}\]
control(num_ctrl_qubits: int = 1, label: str | None = None, ctrl_state: str | int | None = None) → ControlledGate

Method to return a controlled version of the gate.

Parameters:

  • num_ctrl_qubits – Number of control qubits for the gate. Defaults to 1.

  • label – An optional label for the gate. Defaults to None.

  • ctrl_state – The control qubit state to use (e.g. ‘00’). Defaults to None.

Returns:

The qiskit.circuit.ControlledGate version of the gate.

inverse() → iXdgGate

Inverts iX gate.

Returns:

The inverse iX gate.

class qiskit_superstaq.custom_gates.iXdgGate(label: str | None = None)

Bases: Gate

The conjugate transpose of the iXGate (\(iXGate^{\dagger} = iXdgGate\)).

control(num_ctrl_qubits: int = 1, label: str | None = None, ctrl_state: str | int | None = None) → ControlledGate

Method to return a controlled version of the gate.

Parameters:

  • num_ctrl_qubits – Number of control qubits for the gate. Defaults to 1.

  • label – An optional label for the gate. Defaults to None.

  • ctrl_state – The control qubit state to use (e.g. ‘00’). Defaults to None.

Returns:

The qiskit.circuit.ControlledGate version of the gate.

inverse() → iXGate

Inverts the iXdgGate.

Returns:

The inverse of the iXdgGate.

qiskit_superstaq.serialization module

qiskit_superstaq.serialization.deserialize_circuits(serialized_circuits: str) → List[QuantumCircuit]

Deserialize serialized `qiskit.QuantumCircuit`(s).

Parameters:

serialized_circuits – String generated via qss.serialization.serialize_circuit().

Returns:

A list containing the deserialized circuits.

Raises:

ValueError – If serialized_circuits can’t be deserialized.

qiskit_superstaq.serialization.json_encoder(val: object) → Dict[str, str | int | float | List[int | float | List[RealArray]]]

Convert (real or complex) arrays to a JSON-serializable format.

Parameters:

val – The value to be serialized.

Returns:

A JSON dictionary containing the provided name and array values.

Raises:

TypeError – If val is not a np.ndarray.

qiskit_superstaq.serialization.json_resolver(val: T) → T | ndarray[Any, dtype[complex128]]

Hook to deserialize objects that were serialized via json_encoder().

Parameters:

val – The deserialized object.

Returns:

The resolved object.

qiskit_superstaq.serialization.serialize_circuits(circuits: QuantumCircuit | Sequence[QuantumCircuit]) → str

Serialize QuantumCircuit(s) into a single string.

Parameters:

circuits – A qiskit.QuantumCircuit or list of `qiskit.QuantumCircuit`s to be serialized.

Returns:

A string representing the serialized circuit(s).

qiskit_superstaq.serialization.to_json(val: object) → str

Extends json.dumps to support numpy arrays.

Parameters:

val – The value to be serialized.

Returns:

The JSON-serialized value (a string).

qiskit_superstaq.superstaq_backend module

class qiskit_superstaq.superstaq_backend.SuperstaqBackend(provider: SuperstaqProvider, target: str)

Bases: BackendV1

This class represents a Superstaq backend.

aqt_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], *, num_eca_circuits: int | None = None, random_seed: int | None = None, atol: float | None = None, gate_defs: Mapping[str, str | ndarray[Any, dtype[complex128]] | None] | None = None, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for the Advanced Quantum Testbed (AQT).

AQT is a superconducting transmon quantum computing testbed at Lawrence Berkeley National Laboratory. More information can be found at https://aqt.lbl.gov.

Specifying a nonzero value for num_eca_circuits enables compilation with Equivalent Circuit Averaging (ECA). See https://arxiv.org/abs/2111.04572 for a description of ECA.

Parameters:

  • circuits – The circuit(s) to compile.

  • num_eca_circuits – Optional number of logically equivalent random circuits to generate from each input circuit for Equivalent Circuit Averaging (ECA).

  • random_seed – Optional seed used for approximate synthesis and ECA.

  • atol – An optional tolerance to use for approximate gate synthesis.

  • gate_defs – An optional dictionary mapping names in qtrl configs to operations, where each operation can be either a unitary matrix or None. More specific associations take precedence, for example {“SWAP”: <matrix1>, “SWAP/C5C4”: <matrix2>} implies <matrix1> for all “SWAP” calibrations except “SWAP/C5C4” (which will instead be mapped to <matrix2> applied to qubits 4 and 5). Setting any calibration to None will disable that calibration.

  • kwargs – Other desired compile options.

Returns:

Object whose .circuit(s) attribute contains the optimized circuits(s). Alternatively for ECA, an Object whose .circuits attribute is a list (or list of lists) of logically equivalent circuits. If qtrl is installed, the object’s .seq attribute is a qtrl Sequence object containing pulse sequences for each compiled circuit, and its .pulse_list(s) attribute contains the corresponding list(s) of cycles.

Raises:

ValueError – If this is not an AQT backend.

compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], **kwargs: Any) → CompilerOutput

Compiles the given circuit(s) to the backend’s native gateset.

Parameters:

  • circuits – The qiskit QuantumCircuit(s) to compile.

  • kwargs – Other desired compile options.

Returns:

A CompilerOutput object whose .circuit(s) attribute contains optimized compiled circuit(s).

Raises:

ValueError – If this backend does not support compilation.

cq_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], *, grid_shape: Tuple[int, int] | None = None, control_radius: float = 1.0, stripped_cz_rads: float = 0.0, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for CQ devices.

Parameters:

  • circuits – The qiskit QuantumCircuit(s) to compile.

  • grid_shape – Optional fixed dimensions for the rectangular qubit grid (by default the actual qubit layout will be pulled from the hardware provider).

  • control_radius – The radius with which qubits remain connected (ie 1.0 indicates nearest neighbor connectivity).

  • stripped_cz_rads – The angle in radians of the stripped cz gate.

  • kwargs – Other desired compile options.

Returns:

An CQ CompilerOutput object.

Raises:

ValueError – If this is not a CQ backend.

ibmq_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], dynamical_decoupling: bool = True, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for IBMQ devices.

Parameters:

  • circuits – The qiskit QuantumCircuit(s) to compile.

  • dynamical_decoupling – Applies dynamical decoupling optimization to circuit(s).

  • kwargs – Other desired compile options.

Returns:

Object whose .circuit(s) attribute contains the compiled circuits(s), and whose .pulse_gate_circuit(s) attribute contains the corresponding pulse schedule(s) (when available).

Raises:

ValueError – If this is not an IBMQ backend.

process_aces(job_id: str) → List[float]

Process a job submitted through submit_aces.

Parameters:

job_id – The job id returned by submit_aces.

Returns:

The estimated eigenvalues.

qscout_compile(circuits: qiskit.QuantumCircuit | Sequence[qiskit.QuantumCircuit], *, mirror_swaps: bool = False, base_entangling_gate: str = 'xx', num_qubits: int | None = None, error_rates: SupportsItems[tuple[int, ...], float] | None = None, **kwargs: Any) → qss.compiler_output.CompilerOutput

Compiles and optimizes the given circuit(s) for the QSCOUT trapped-ion testbed at Sandia National Laboratories [1].

Compiled circuits are returned as both qiskit.QuantumCircuit objects and corresponding Jaqal [2] programs (strings).

References

[1] S. M. Clark et al., *Engineering the Quantum Scientific Computing Open User

Testbed*, IEEE Transactions on Quantum Engineering Vol. 2, 3102832 (2021). https://doi.org/10.1109/TQE.2021.3096480.

[2] B. Morrison, et al., Just Another Quantum Assembly Language (Jaqal), 2020 IEEE

International Conference on Quantum Computing and Engineering (QCE), 402-408 (2020). https://arxiv.org/abs/2008.08042.

Parameters:

  • circuits – The circuit(s) to compile.

  • mirror_swaps – Whether to use mirror swapping to reduce two-qubit gate overhead.

  • base_entangling_gate – The base entangling gate to use (“xx”, “zz”, “sxx”, or “szz”). Compilation with the “xx” and “zz” entangling bases will use arbitrary parameterized two-qubit interactions, while the “sxx” and “szz” bases will only use fixed maximally-entangling rotations.

  • num_qubits – An optional number of qubits that should be present in the compiled circuit(s) and Jaqal program(s) (otherwise this will be determined from the input).

  • error_rates – Optional dictionary assigning relative error rates to pairs of physical qubits, in the form {<qubit_indices>: <error_rate>, …} where <qubit_indices> is a tuple physical qubit indices (ints) and <error_rate> is a relative error rate for gates acting on those qubits (for example {(0, 1): 0.3, (1, 2): 0.2}) . If provided, Superstaq will attempt to map the circuit to minimize the total error on each qubit.

  • kwargs – Other desired qscout_compile options.

Returns:

Object whose .circuit(s) attribute contains optimized qiskit QuantumCircuit`(s), and `.jaqal_program(s) attribute contains the corresponding Jaqal program(s).

Raises:

  • ValueError – If this is not a Sandia backend.

  • ValueError – If base_entangling_gate is not a valid entangling basis.

resource_estimate(circuits: QuantumCircuit | Sequence[QuantumCircuit]) → ResourceEstimate | List[ResourceEstimate]

Generates resource estimates for qiskit circuit(s).

Parameters:

circuits – The circuit(s) used during resource estimation.

Returns:

ResourceEstimate(s) containing resource costs (after compilation) for running circuit(s) on this backend.

retrieve_job(job_id: str) → SuperstaqJob

Gets a job that has been created on the Superstaq API.

Parameters:

  • job_id – The UUID of the job. Jobs are assigned these numbers by the server during the

  • job. (creation of the) –

Returns:

A qss.SuperstaqJob which can be queried for status or results.

Raises:

SuperstaqServerException – If there was an error accessing the API.

run(circuits: QuantumCircuit | Sequence[QuantumCircuit], shots: int, method: str | None = None, **kwargs: Any) → SuperstaqJob

Runs circuits on the stored Superstaq backend.

Parameters:

  • circuits – A list of circuits to run.

  • shots – The number of execution shots (times to run the circuit).

  • method – An optional string that describes the execution method (e.g. ‘dry-run’, ‘statevector’, etc.).

  • kwargs – Other optimization and execution parameters.

Returns:

A Superstaq job storing ID and other related info.

Raises:

ValueError – If circuits contains invalid circuits for submission.

submit_aces(qubits: Sequence[int], shots: int, num_circuits: int, mirror_depth: int, extra_depth: int, method: str | None = None, noise: str | None = None, error_prob: float | Tuple[float, float, float] | None = None, tag: str | None = None, lifespan: int | None = None) → str

Submits the jobs to characterize this target through the ACES protocol.

The following gate eigenvalues are eestimated. For each qubit in the device, we consider six Clifford gates. These are given by the XZ maps: XZ, ZX, -YZ, -XY, ZY, YX. For each of these gates, three eigenvalues are returned (X, Y, Z, in that order). Then, the two-qubit gate considered here is the CZ in linear connectivity (each qubit n with n + 1). For this gate, 15 eigenvalues are considered: XX, XY, XZ, XI, YX, YY, YZ, YI, ZX, ZY, ZZ, ZI, IX, IY IZ, in that order.

If n qubits are characterized, the first 18 * n entries of the list returned by process_aces will contain the single-qubit eigenvalues for each gate in the order above. After all the single-qubit eigenvalues, the next 15 * (n - 1) entries will contain for the CZ connections, in ascending order.

The protocol in detail can be found in: https://arxiv.org/abs/2108.05803.

Parameters:

  • qubits – A list with the qubit indices to characterize.

  • shots – How many shots to use per circuit submitted.

  • num_circuits – How many random circuits to use in the protocol.

  • mirror_depth – The half-depth of the mirror portion of the random circuits.

  • extra_depth – The depth of the fully random portion of the random circuits.

  • method – Which type of method to execute the circuits with.

  • noise – Noise model to simulate the protocol with. Valid strings are “symmetric_depolarize”, “phase_flip”, “bit_flip” and “asymmetric_depolarize”.

  • error_prob – The error probabilities if a string was passed to noise. * For “asymmetric_depolarize”, error_prob will be a three-tuple with the error rates for the X, Y, Z gates in that order. So, a valid argument would be error_prob = (0.1, 0.1, 0.1). Notice that these values must add up to less than or equal to 1. * For the other channels, error_prob is one number less than or equal to 1, e.g., error_prob = 0.1.

  • tag – Tag for all jobs submitted for this protocol.

  • lifespan – How long to store the jobs submitted for in days (only works with right permissions).

Returns:

A string with the job id for the ACES job created.

Raises:
target_info() → Dict[str, Any]

Returns information about this backend.

Returns:

A dictionary of target information.

qiskit_superstaq.superstaq_job module

class qiskit_superstaq.superstaq_job.SuperstaqJob(backend: SuperstaqBackend, job_id: str)

Bases: JobV1

This class represents a Superstaq job instance.

ALL_STATES = ('Done', 'Cancelled', 'Failed', 'Queued', 'Submitted', 'Running')
PROCESSING_STATES = ('Queued', 'Submitted', 'Running')
TERMINAL_STATES = ('Done', 'Cancelled', 'Failed')
compiled_circuits() → List[QuantumCircuit]

Gets the compiled circuits that were submitted for this job.

Returns:

A list of compiled circuits.

input_circuits() → List[QuantumCircuit]

Gets the original circuits that were submitted for this job.

Returns:

A list of the submitted input circuits.

result(timeout: float | None = None, wait: float = 5, qubit_indices: Sequence[int] | None = None) → Result

Retrieves the result data associated with a Superstaq job.

Parameters:

  • timeout – An optional parameter that fixes when result retrieval times out. Units are in seconds.

  • wait – An optional parameter that sets the interval to check for Superstaq job results. Units are in seconds. Defaults to 5.

  • qubit_indices – The qubit indices to return the results of individually.

Returns:

A qiskit result object containing job information.

status() → JobStatus

Query for the equivalent qiskit job status.

Returns:

The equivalent qiskit.providers.jobstatus.JobStatus type.

submit() → None

Unsupported submission call.

Raises:

NotImplementedError – If a job is submitted via SuperstaqJob.

to_dict() → Dict[str, Any]

Refreshes and returns job information.

Note

The contents of this dictionary are not guaranteed to be consistent over time. Whenever possible, users should use the specific SuperstaqJob methods to retrieve the desired job information instead of relying on particular entries in the output of this method.

Returns:

A dictionary containing updated job information.

qiskit_superstaq.superstaq_provider module

class qiskit_superstaq.superstaq_provider.SuperstaqProvider(api_key: str | None = None, remote_host: str | None = None, api_version: str = 'v0.2.0', max_retry_seconds: int = 3600, verbose: bool = False, **kwargs: Any)

Bases: ProviderV1, Service

Provider for Superstaq backend.

Typical usage is:

import qiskit_superstaq as qss

ss_provider = qss.SuperstaqProvider('MY_TOKEN')

backend = ss_provider.get_backend('target')

where MY_TOKEN is the access token provided by Superstaq, and target is the name of the desired backend.

aqt_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], target: str = 'aqt_keysight_qpu', *, num_eca_circuits: int | None = None, random_seed: int | None = None, atol: float | None = None, gate_defs: Mapping[str, str | ndarray[Any, dtype[complex128]] | None] | None = None, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for the Advanced Quantum Testbed (AQT).

AQT is a superconducting transmon quantum computing testbed at Lawrence Berkeley National Laboratory. More information can be found at https://aqt.lbl.gov.

Specifying a nonzero value for num_eca_circuits enables compilation with Equivalent Circuit Averaging (ECA). See https://arxiv.org/abs/2111.04572 for a description of ECA.

Parameters:

  • circuits – The circuit(s) to compile.

  • target – A string containing the name of a target AQT backend.

  • num_eca_circuits – Optional number of logically equivalent random circuits to generate from each input circuit for Equivalent Circuit Averaging (ECA).

  • random_seed – Optional seed used for approximate synthesis and ECA.

  • atol – An optional tolerance to use for approximate gate synthesis.

  • gate_defs – An optional dictionary mapping names in qtrl configs to operations, where each operation can be either a unitary matrix or None. More specific associations take precedence, for example {“SWAP”: <matrix1>, “SWAP/C5C4”: <matrix2>} implies <matrix1> for all “SWAP” calibrations except “SWAP/C5C4” (which will instead be mapped to <matrix2> applied to qubits 4 and 5). Setting any calibration to None will disable that calibration.

  • kwargs – Other desired compile options.

Returns:

Object whose .circuit(s) attribute contains the optimized circuits(s). Alternatively for ECA, an Object whose .circuits attribute is a list (or list of lists) of logically equivalent circuits. If qtrl is installed, the object’s .seq attribute is a qtrl Sequence object containing pulse sequences for each compiled circuit, and its .pulse_list(s) attribute contains the corresponding list(s) of cycles.

Raises:

ValueError – If target is not a valid AQT target.

aqt_compile_eca(circuits: QuantumCircuit | Sequence[QuantumCircuit], num_equivalent_circuits: int, random_seed: int | None = None, target: str = 'aqt_keysight_qpu', atol: float | None = None, gate_defs: Mapping[str, str | ndarray[Any, dtype[complex128]] | None] | None = None, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for the Advanced Quantum Testbed (AQT) at Lawrence Berkeley National Laboratory using Equivalent Circuit Averaging (ECA).

See arxiv.org/pdf/2111.04572.pdf for a description of ECA.

Note

This method has been deprecated. Instead, use the num_eca_circuits argument of aqt_compile().

Parameters:

  • circuits – The circuit(s) to compile.

  • num_equivalent_circuits – Number of logically equivalent random circuits to generate for each input circuit.

  • random_seed – Optional seed for circuit randomizer.

  • target – A string containing the name of a target AQT backend.

  • atol – An optional tolerance to use for approximate gate synthesis.

  • gate_defs – An optional dictionary mapping names in qtrl configs to operations, where each operation can be either a unitary matrix or None. More specific associations take precedence, for example {“SWAP”: <matrix1>, “SWAP/C5C4”: <matrix2>} implies <matrix1> for all “SWAP” calibrations except “SWAP/C5C4” (which will instead be mapped to <matrix2> applied to qubits 4 and 5). Setting any calibration to None will disable that calibration.

  • kwargs – Other desired aqt_compile_eca options.

Returns:

Object whose .circuits attribute is a list (or list of lists) of logically equivalent circuits. If qtrl is installed, the object’s .seq attribute is a qtrl Sequence object containing pulse sequences for each compiled circuit, and its .pulse_list(s) attribute contains the corresponding list(s) of cycles.

Raises:

ValueError – If target is not a valid AQT target.

backends() → List[SuperstaqBackend]

Lists the backends available from this provider.

Returns:

A list of Superstaq backends.

cq_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], target: str = 'cq_hilbert_qpu', *, grid_shape: Tuple[int, int] | None = None, control_radius: float = 1.0, stripped_cz_rads: float = 0.0, **kwargs: Any) → CompilerOutput

Compiles the given circuit(s) to CQ device, optimized to its native gate set.

Parameters:

  • circuits – The circuit(s) to compile.

  • target – String of target CQ device.

  • grid_shape – Optional fixed dimensions for the rectangular qubit grid (by default the actual qubit layout will be pulled from the hardware provider).

  • control_radius – The radius with which qubits remain connected (ie 1.0 indicates nearest neighbor connectivity).

  • stripped_cz_rads – The angle in radians of the stripped cz gate.

  • kwargs – Other desired cq_compile options.

Returns:

object whose .circuit(s) attribute is an optimized qiskit circuit(s).

Raises:

ValueError – If target is not a valid CQ target.

get_backend(target: str) → SuperstaqBackend

Returns a Superstaq backend.

Parameters:

target – A string containing the name of a target backend.

Returns:

A Superstaq backend.

get_targets() → Dict[str, Any]

Gets list of targets.

Returns:

A dictionary sorted by “compile-only”, “compile-and-run”, “unavailable”, and “retired”.

ibmq_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], target: str = 'ibmq_qasm_simulator', **kwargs: Any) → CompilerOutput

Returns pulse schedule(s) for the given qiskit circuit(s) and target.

Parameters:

  • circuits – The circuit(s) to compile.

  • target – A string containing the name of a target IBMQ backend.

  • kwargs – Other desired ibmq_compile options.

Returns:

Object whose .circuit(s) attribute contains the compiled circuits(s), and whose .pulse_gate_circuit(s) attribute contains the corresponding pulse schedule(s) (when available).

Raises:

ValueError – If target is not a valid IBMQ target.

process_dfe(ids: List[str]) → float

Process the results of a DFE protocol.

Parameters:

ids – A list (size two) of ids returned by a call to submit_dfe.

Returns:

The estimated fidelity between the two states as a float.

Raises:

  • ValueError – If ids is not of size two.

  • SuperstaqServerException – If there was an error accesing the API or the jobs submitted through submit_dfe have not finished running.

qscout_compile(circuits: qiskit.QuantumCircuit | Sequence[qiskit.QuantumCircuit], target: str = 'sandia_qscout_qpu', *, mirror_swaps: bool = False, base_entangling_gate: str = 'xx', num_qubits: int | None = None, error_rates: SupportsItems[tuple[int, ...], float] | None = None, **kwargs: Any) → qss.compiler_output.CompilerOutput

Compiles and optimizes the given circuit(s) for the QSCOUT trapped-ion testbed at Sandia National Laboratories [1].

Compiled circuits are returned as both qiskit.QuantumCircuit objects and corresponding Jaqal [2] programs (strings).

References

[1] S. M. Clark et al., *Engineering the Quantum Scientific Computing Open User

Testbed*, IEEE Transactions on Quantum Engineering Vol. 2, 3102832 (2021). https://doi.org/10.1109/TQE.2021.3096480.

[2] B. Morrison, et al., Just Another Quantum Assembly Language (Jaqal), 2020 IEEE

International Conference on Quantum Computing and Engineering (QCE), 402-408 (2020). https://arxiv.org/abs/2008.08042.

Parameters:

  • circuits – The circuit(s) to compile.

  • target – A string containing the name of a target backend.

  • mirror_swaps – Whether to use mirror swapping to reduce two-qubit gate overhead.

  • base_entangling_gate – The base entangling gate to use (“xx”, “zz”, “sxx”, or “szz”). Compilation with the “xx” and “zz” entangling bases will use arbitrary parameterized two-qubit interactions, while the “sxx” and “szz” bases will only use fixed maximally-entangling rotations.

  • num_qubits – An optional number of qubits that should be present in the compiled circuit(s) and Jaqal program(s) (otherwise this will be determined from the input).

  • error_rates – Optional dictionary assigning relative error rates to pairs of physical qubits, in the form {<qubit_indices>: <error_rate>, …} where <qubit_indices> is a tuple physical qubit indices (ints) and <error_rate> is a relative error rate for gates acting on those qubits (for example {(0, 1): 0.3, (1, 2): 0.2}) . If provided, Superstaq will attempt to map the circuit to minimize the total error on each qubit.

  • kwargs – Other desired qscout_compile options.

Returns:

Object whose .circuit(s) attribute contains optimized qiskit QuantumCircuit`(s), and `.jaqal_program(s) attribute contains the corresponding Jaqal program(s).

Raises:

  • ValueError – If target is not a valid Sandia target.

  • ValueError – If base_entangling_gate is not a valid gate option.

resource_estimate(circuits: QuantumCircuit | Sequence[QuantumCircuit], target: str) → ResourceEstimate | List[ResourceEstimate]

Generates resource estimates for qiskit circuit(s).

Parameters:

  • circuits – The circuit(s) used during resource estimation.

  • target – A string containing the name of a target backend.

Returns:

ResourceEstimate(s) containing resource costs (after compilation) for running circuit(s) on a backend.

submit_dfe(rho_1: Tuple[QuantumCircuit, str], rho_2: Tuple[QuantumCircuit, str], num_random_bases: int, shots: int, **kwargs: Any) → List[str]

Executes the circuits neccessary for the DFE protocol.

The circuits used to prepare the desired states should not contain final measurements, but can contain mid-circuit measurements (as long as the intended target supports them). For example, to prepare a Bell state to be ran in ss_unconstrained_simulator, you should pass qc = qiskit.QuantumCircuit(2); qc.h(0); qc.cx(0, 1) as the first element of some rho_i (note there are no final measurements).

The fidelity between states is calculated following the random measurement protocol outlined in [1].

References

[1] Elben, Andreas, Benoît Vermersch, Rick van Bijnen, Christian Kokail, Tiff Brydges,

Christine Maier, Manoj K. Joshi, Rainer Blatt, Christian F. Roos, and Peter Zoller. “Cross-platform verification of intermediate scale quantum devices.” Physical review letters 124, no. 1 (2020): 010504.

Parameters:

  • rho_1 – Tuple containing the information to prepare the first state. It contains a qiskit.QuantumCircuit at index 0 and a target name at index 1.

  • rho_2 – Tuple containing the information to prepare the second state. It contains a qiskit.QuantumCircuit at index 0 and a target name at index 1.

  • num_random_bases – Number of random bases to measure each state in.

  • shots – Number of shots to use per random basis.

  • kwargs – Other execution parameters. - tag: Tag for all jobs submitted for this protocol. - lifespan: How long to store the jobs submitted for in days (only works with right permissions). - method: Which type of method to execute the circuits with.

Returns:

A list with two strings, which are the job ids that need to be passed to process_dfe to post-process the measurement results and return the fidelity.

Raises:

  • ValueError – If circuit is not a valid qiskit.QuantumCircuit.

  • SuperstaqServerException – If there was an error accessing the API.

supercheq(files: List[List[int]], num_qubits: int, depth: int) → Tuple[List[QuantumCircuit], ndarray[Any, dtype[float64]]]

Returns Supercheq randomly generated circuits and the corresponding fidelity matrices.

References

[1] P. Gokhale et al., SupercheQ: Quantum Advantage for Distributed Databases, (2022).

https://arxiv.org/abs/2212.03850.

Parameters:

  • files – A list of files specified as binary using ints. For example: [[1, 0, 1], [1, 1, 1]].

  • num_qubits – The number of qubits to run Supercheq on.

  • depth – The depth of the circuits to run Supercheq on.

Returns:

A tuple containing a list of `qiskit.QuantumCircuit`s and a list of corresponding

fidelity matrices.

qiskit_superstaq.validation module

qiskit_superstaq.validation.validate_qiskit_circuits(circuits: object) → None

Validates that the input is either a single qiskit.QuantumCircuit or a list of qiskit.QuantumCircuit instances.

Parameters:

circuits – The circuit(s) to run.

Raises:

  • ValueError – If the input is not a qiskit.QuantumCircuit or a list of

  • qiskit.QuantumCircuit –

Module contents

class qiskit_superstaq.AQTiCCXGate(label: str | None = None)

Bases: iCCXGate

A subclass of the iCCXGate for AQT where the control state is “00”.

qiskit_superstaq.AQTiToffoliGate

alias of AQTiCCXGate

class qiskit_superstaq.AceCR(rads: str | float = 1.5707963267948966, sandwich_rx_rads: float = 0, label: str | None = None)

Bases: Gate

Active Cancellation Echoed Cross Resonance gate, supporting polarity switches and sandwiches.

The typical AceCR in the literature is a positive half-CR, then X on “Z side”, then negative half-CR (where “Z side” and “X side” refer to the two sides of the underlying ZX interactions).

inverse() → AceCR

Inverts the AceCR gate.

Returns:

The inverse AceCR gate.

class qiskit_superstaq.ParallelGates(*component_gates: Gate, label: str | None = None)

Bases: Gate

A single gate combining a collection of concurrent gate(s) acting on different qubits.

inverse() → ParallelGates

Inverts parallel gates.

Returns:

The inverse parallel gates.

class qiskit_superstaq.StrippedCZGate(rz_rads: float)

Bases: Gate

The Stripped CZ gate is a regular CZ gate when the rz angle = 0.

It is the gate that is actually being performed by Hilbert, and it is corrected into a CZ gate by RZ gates afterwards if the rz angle is nonzero.

inverse() → StrippedCZGate

Inverts the stripped CZ gate.

Returns:

The inverse Stripped CZ gate.

class qiskit_superstaq.SuperstaqBackend(provider: SuperstaqProvider, target: str)

Bases: BackendV1

This class represents a Superstaq backend.

aqt_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], *, num_eca_circuits: int | None = None, random_seed: int | None = None, atol: float | None = None, gate_defs: Mapping[str, str | ndarray[Any, dtype[complex128]] | None] | None = None, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for the Advanced Quantum Testbed (AQT).

AQT is a superconducting transmon quantum computing testbed at Lawrence Berkeley National Laboratory. More information can be found at https://aqt.lbl.gov.

Specifying a nonzero value for num_eca_circuits enables compilation with Equivalent Circuit Averaging (ECA). See https://arxiv.org/abs/2111.04572 for a description of ECA.

Parameters:

  • circuits – The circuit(s) to compile.

  • num_eca_circuits – Optional number of logically equivalent random circuits to generate from each input circuit for Equivalent Circuit Averaging (ECA).

  • random_seed – Optional seed used for approximate synthesis and ECA.

  • atol – An optional tolerance to use for approximate gate synthesis.

  • gate_defs – An optional dictionary mapping names in qtrl configs to operations, where each operation can be either a unitary matrix or None. More specific associations take precedence, for example {“SWAP”: <matrix1>, “SWAP/C5C4”: <matrix2>} implies <matrix1> for all “SWAP” calibrations except “SWAP/C5C4” (which will instead be mapped to <matrix2> applied to qubits 4 and 5). Setting any calibration to None will disable that calibration.

  • kwargs – Other desired compile options.

Returns:

Object whose .circuit(s) attribute contains the optimized circuits(s). Alternatively for ECA, an Object whose .circuits attribute is a list (or list of lists) of logically equivalent circuits. If qtrl is installed, the object’s .seq attribute is a qtrl Sequence object containing pulse sequences for each compiled circuit, and its .pulse_list(s) attribute contains the corresponding list(s) of cycles.

Raises:

ValueError – If this is not an AQT backend.

compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], **kwargs: Any) → CompilerOutput

Compiles the given circuit(s) to the backend’s native gateset.

Parameters:

  • circuits – The qiskit QuantumCircuit(s) to compile.

  • kwargs – Other desired compile options.

Returns:

A CompilerOutput object whose .circuit(s) attribute contains optimized compiled circuit(s).

Raises:

ValueError – If this backend does not support compilation.

cq_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], *, grid_shape: Tuple[int, int] | None = None, control_radius: float = 1.0, stripped_cz_rads: float = 0.0, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for CQ devices.

Parameters:

  • circuits – The qiskit QuantumCircuit(s) to compile.

  • grid_shape – Optional fixed dimensions for the rectangular qubit grid (by default the actual qubit layout will be pulled from the hardware provider).

  • control_radius – The radius with which qubits remain connected (ie 1.0 indicates nearest neighbor connectivity).

  • stripped_cz_rads – The angle in radians of the stripped cz gate.

  • kwargs – Other desired compile options.

Returns:

An CQ CompilerOutput object.

Raises:

ValueError – If this is not a CQ backend.

ibmq_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], dynamical_decoupling: bool = True, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for IBMQ devices.

Parameters:

  • circuits – The qiskit QuantumCircuit(s) to compile.

  • dynamical_decoupling – Applies dynamical decoupling optimization to circuit(s).

  • kwargs – Other desired compile options.

Returns:

Object whose .circuit(s) attribute contains the compiled circuits(s), and whose .pulse_gate_circuit(s) attribute contains the corresponding pulse schedule(s) (when available).

Raises:

ValueError – If this is not an IBMQ backend.

process_aces(job_id: str) → List[float]

Process a job submitted through submit_aces.

Parameters:

job_id – The job id returned by submit_aces.

Returns:

The estimated eigenvalues.

qscout_compile(circuits: qiskit.QuantumCircuit | Sequence[qiskit.QuantumCircuit], *, mirror_swaps: bool = False, base_entangling_gate: str = 'xx', num_qubits: int | None = None, error_rates: SupportsItems[tuple[int, ...], float] | None = None, **kwargs: Any) → qss.compiler_output.CompilerOutput

Compiles and optimizes the given circuit(s) for the QSCOUT trapped-ion testbed at Sandia National Laboratories [1].

Compiled circuits are returned as both qiskit.QuantumCircuit objects and corresponding Jaqal [2] programs (strings).

References

[1] S. M. Clark et al., *Engineering the Quantum Scientific Computing Open User

Testbed*, IEEE Transactions on Quantum Engineering Vol. 2, 3102832 (2021). https://doi.org/10.1109/TQE.2021.3096480.

[2] B. Morrison, et al., Just Another Quantum Assembly Language (Jaqal), 2020 IEEE

International Conference on Quantum Computing and Engineering (QCE), 402-408 (2020). https://arxiv.org/abs/2008.08042.

Parameters:

  • circuits – The circuit(s) to compile.

  • mirror_swaps – Whether to use mirror swapping to reduce two-qubit gate overhead.

  • base_entangling_gate – The base entangling gate to use (“xx”, “zz”, “sxx”, or “szz”). Compilation with the “xx” and “zz” entangling bases will use arbitrary parameterized two-qubit interactions, while the “sxx” and “szz” bases will only use fixed maximally-entangling rotations.

  • num_qubits – An optional number of qubits that should be present in the compiled circuit(s) and Jaqal program(s) (otherwise this will be determined from the input).

  • error_rates – Optional dictionary assigning relative error rates to pairs of physical qubits, in the form {<qubit_indices>: <error_rate>, …} where <qubit_indices> is a tuple physical qubit indices (ints) and <error_rate> is a relative error rate for gates acting on those qubits (for example {(0, 1): 0.3, (1, 2): 0.2}) . If provided, Superstaq will attempt to map the circuit to minimize the total error on each qubit.

  • kwargs – Other desired qscout_compile options.

Returns:

Object whose .circuit(s) attribute contains optimized qiskit QuantumCircuit`(s), and `.jaqal_program(s) attribute contains the corresponding Jaqal program(s).

Raises:

  • ValueError – If this is not a Sandia backend.

  • ValueError – If base_entangling_gate is not a valid entangling basis.

resource_estimate(circuits: QuantumCircuit | Sequence[QuantumCircuit]) → ResourceEstimate | List[ResourceEstimate]

Generates resource estimates for qiskit circuit(s).

Parameters:

circuits – The circuit(s) used during resource estimation.

Returns:

ResourceEstimate(s) containing resource costs (after compilation) for running circuit(s) on this backend.

retrieve_job(job_id: str) → SuperstaqJob

Gets a job that has been created on the Superstaq API.

Parameters:

  • job_id – The UUID of the job. Jobs are assigned these numbers by the server during the

  • job. (creation of the) –

Returns:

A qss.SuperstaqJob which can be queried for status or results.

Raises:

SuperstaqServerException – If there was an error accessing the API.

run(circuits: QuantumCircuit | Sequence[QuantumCircuit], shots: int, method: str | None = None, **kwargs: Any) → SuperstaqJob

Runs circuits on the stored Superstaq backend.

Parameters:

  • circuits – A list of circuits to run.

  • shots – The number of execution shots (times to run the circuit).

  • method – An optional string that describes the execution method (e.g. ‘dry-run’, ‘statevector’, etc.).

  • kwargs – Other optimization and execution parameters.

Returns:

A Superstaq job storing ID and other related info.

Raises:

ValueError – If circuits contains invalid circuits for submission.

submit_aces(qubits: Sequence[int], shots: int, num_circuits: int, mirror_depth: int, extra_depth: int, method: str | None = None, noise: str | None = None, error_prob: float | Tuple[float, float, float] | None = None, tag: str | None = None, lifespan: int | None = None) → str

Submits the jobs to characterize this target through the ACES protocol.

The following gate eigenvalues are eestimated. For each qubit in the device, we consider six Clifford gates. These are given by the XZ maps: XZ, ZX, -YZ, -XY, ZY, YX. For each of these gates, three eigenvalues are returned (X, Y, Z, in that order). Then, the two-qubit gate considered here is the CZ in linear connectivity (each qubit n with n + 1). For this gate, 15 eigenvalues are considered: XX, XY, XZ, XI, YX, YY, YZ, YI, ZX, ZY, ZZ, ZI, IX, IY IZ, in that order.

If n qubits are characterized, the first 18 * n entries of the list returned by process_aces will contain the single-qubit eigenvalues for each gate in the order above. After all the single-qubit eigenvalues, the next 15 * (n - 1) entries will contain for the CZ connections, in ascending order.

The protocol in detail can be found in: https://arxiv.org/abs/2108.05803.

Parameters:

  • qubits – A list with the qubit indices to characterize.

  • shots – How many shots to use per circuit submitted.

  • num_circuits – How many random circuits to use in the protocol.

  • mirror_depth – The half-depth of the mirror portion of the random circuits.

  • extra_depth – The depth of the fully random portion of the random circuits.

  • method – Which type of method to execute the circuits with.

  • noise – Noise model to simulate the protocol with. Valid strings are “symmetric_depolarize”, “phase_flip”, “bit_flip” and “asymmetric_depolarize”.

  • error_prob – The error probabilities if a string was passed to noise. * For “asymmetric_depolarize”, error_prob will be a three-tuple with the error rates for the X, Y, Z gates in that order. So, a valid argument would be error_prob = (0.1, 0.1, 0.1). Notice that these values must add up to less than or equal to 1. * For the other channels, error_prob is one number less than or equal to 1, e.g., error_prob = 0.1.

  • tag – Tag for all jobs submitted for this protocol.

  • lifespan – How long to store the jobs submitted for in days (only works with right permissions).

Returns:

A string with the job id for the ACES job created.

Raises:
target_info() → Dict[str, Any]

Returns information about this backend.

Returns:

A dictionary of target information.

class qiskit_superstaq.SuperstaqJob(backend: SuperstaqBackend, job_id: str)

Bases: JobV1

This class represents a Superstaq job instance.

ALL_STATES = ('Done', 'Cancelled', 'Failed', 'Queued', 'Submitted', 'Running')
PROCESSING_STATES = ('Queued', 'Submitted', 'Running')
TERMINAL_STATES = ('Done', 'Cancelled', 'Failed')
compiled_circuits() → List[QuantumCircuit]

Gets the compiled circuits that were submitted for this job.

Returns:

A list of compiled circuits.

input_circuits() → List[QuantumCircuit]

Gets the original circuits that were submitted for this job.

Returns:

A list of the submitted input circuits.

result(timeout: float | None = None, wait: float = 5, qubit_indices: Sequence[int] | None = None) → Result

Retrieves the result data associated with a Superstaq job.

Parameters:

  • timeout – An optional parameter that fixes when result retrieval times out. Units are in seconds.

  • wait – An optional parameter that sets the interval to check for Superstaq job results. Units are in seconds. Defaults to 5.

  • qubit_indices – The qubit indices to return the results of individually.

Returns:

A qiskit result object containing job information.

status() → JobStatus

Query for the equivalent qiskit job status.

Returns:

The equivalent qiskit.providers.jobstatus.JobStatus type.

submit() → None

Unsupported submission call.

Raises:

NotImplementedError – If a job is submitted via SuperstaqJob.

to_dict() → Dict[str, Any]

Refreshes and returns job information.

Note

The contents of this dictionary are not guaranteed to be consistent over time. Whenever possible, users should use the specific SuperstaqJob methods to retrieve the desired job information instead of relying on particular entries in the output of this method.

Returns:

A dictionary containing updated job information.

class qiskit_superstaq.SuperstaqProvider(api_key: str | None = None, remote_host: str | None = None, api_version: str = 'v0.2.0', max_retry_seconds: int = 3600, verbose: bool = False, **kwargs: Any)

Bases: ProviderV1, Service

Provider for Superstaq backend.

Typical usage is:

import qiskit_superstaq as qss

ss_provider = qss.SuperstaqProvider('MY_TOKEN')

backend = ss_provider.get_backend('target')

where MY_TOKEN is the access token provided by Superstaq, and target is the name of the desired backend.

aqt_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], target: str = 'aqt_keysight_qpu', *, num_eca_circuits: int | None = None, random_seed: int | None = None, atol: float | None = None, gate_defs: Mapping[str, str | ndarray[Any, dtype[complex128]] | None] | None = None, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for the Advanced Quantum Testbed (AQT).

AQT is a superconducting transmon quantum computing testbed at Lawrence Berkeley National Laboratory. More information can be found at https://aqt.lbl.gov.

Specifying a nonzero value for num_eca_circuits enables compilation with Equivalent Circuit Averaging (ECA). See https://arxiv.org/abs/2111.04572 for a description of ECA.

Parameters:

  • circuits – The circuit(s) to compile.

  • target – A string containing the name of a target AQT backend.

  • num_eca_circuits – Optional number of logically equivalent random circuits to generate from each input circuit for Equivalent Circuit Averaging (ECA).

  • random_seed – Optional seed used for approximate synthesis and ECA.

  • atol – An optional tolerance to use for approximate gate synthesis.

  • gate_defs – An optional dictionary mapping names in qtrl configs to operations, where each operation can be either a unitary matrix or None. More specific associations take precedence, for example {“SWAP”: <matrix1>, “SWAP/C5C4”: <matrix2>} implies <matrix1> for all “SWAP” calibrations except “SWAP/C5C4” (which will instead be mapped to <matrix2> applied to qubits 4 and 5). Setting any calibration to None will disable that calibration.

  • kwargs – Other desired compile options.

Returns:

Object whose .circuit(s) attribute contains the optimized circuits(s). Alternatively for ECA, an Object whose .circuits attribute is a list (or list of lists) of logically equivalent circuits. If qtrl is installed, the object’s .seq attribute is a qtrl Sequence object containing pulse sequences for each compiled circuit, and its .pulse_list(s) attribute contains the corresponding list(s) of cycles.

Raises:

ValueError – If target is not a valid AQT target.

aqt_compile_eca(circuits: QuantumCircuit | Sequence[QuantumCircuit], num_equivalent_circuits: int, random_seed: int | None = None, target: str = 'aqt_keysight_qpu', atol: float | None = None, gate_defs: Mapping[str, str | ndarray[Any, dtype[complex128]] | None] | None = None, **kwargs: Any) → CompilerOutput

Compiles and optimizes the given circuit(s) for the Advanced Quantum Testbed (AQT) at Lawrence Berkeley National Laboratory using Equivalent Circuit Averaging (ECA).

See arxiv.org/pdf/2111.04572.pdf for a description of ECA.

Note

This method has been deprecated. Instead, use the num_eca_circuits argument of aqt_compile().

Parameters:

  • circuits – The circuit(s) to compile.

  • num_equivalent_circuits – Number of logically equivalent random circuits to generate for each input circuit.

  • random_seed – Optional seed for circuit randomizer.

  • target – A string containing the name of a target AQT backend.

  • atol – An optional tolerance to use for approximate gate synthesis.

  • gate_defs – An optional dictionary mapping names in qtrl configs to operations, where each operation can be either a unitary matrix or None. More specific associations take precedence, for example {“SWAP”: <matrix1>, “SWAP/C5C4”: <matrix2>} implies <matrix1> for all “SWAP” calibrations except “SWAP/C5C4” (which will instead be mapped to <matrix2> applied to qubits 4 and 5). Setting any calibration to None will disable that calibration.

  • kwargs – Other desired aqt_compile_eca options.

Returns:

Object whose .circuits attribute is a list (or list of lists) of logically equivalent circuits. If qtrl is installed, the object’s .seq attribute is a qtrl Sequence object containing pulse sequences for each compiled circuit, and its .pulse_list(s) attribute contains the corresponding list(s) of cycles.

Raises:

ValueError – If target is not a valid AQT target.

backends() → List[SuperstaqBackend]

Lists the backends available from this provider.

Returns:

A list of Superstaq backends.

cq_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], target: str = 'cq_hilbert_qpu', *, grid_shape: Tuple[int, int] | None = None, control_radius: float = 1.0, stripped_cz_rads: float = 0.0, **kwargs: Any) → CompilerOutput

Compiles the given circuit(s) to CQ device, optimized to its native gate set.

Parameters:

  • circuits – The circuit(s) to compile.

  • target – String of target CQ device.

  • grid_shape – Optional fixed dimensions for the rectangular qubit grid (by default the actual qubit layout will be pulled from the hardware provider).

  • control_radius – The radius with which qubits remain connected (ie 1.0 indicates nearest neighbor connectivity).

  • stripped_cz_rads – The angle in radians of the stripped cz gate.

  • kwargs – Other desired cq_compile options.

Returns:

object whose .circuit(s) attribute is an optimized qiskit circuit(s).

Raises:

ValueError – If target is not a valid CQ target.

get_backend(target: str) → SuperstaqBackend

Returns a Superstaq backend.

Parameters:

target – A string containing the name of a target backend.

Returns:

A Superstaq backend.

get_targets() → Dict[str, Any]

Gets list of targets.

Returns:

A dictionary sorted by “compile-only”, “compile-and-run”, “unavailable”, and “retired”.

ibmq_compile(circuits: QuantumCircuit | Sequence[QuantumCircuit], target: str = 'ibmq_qasm_simulator', **kwargs: Any) → CompilerOutput

Returns pulse schedule(s) for the given qiskit circuit(s) and target.

Parameters:

  • circuits – The circuit(s) to compile.

  • target – A string containing the name of a target IBMQ backend.

  • kwargs – Other desired ibmq_compile options.

Returns:

Object whose .circuit(s) attribute contains the compiled circuits(s), and whose .pulse_gate_circuit(s) attribute contains the corresponding pulse schedule(s) (when available).

Raises:

ValueError – If target is not a valid IBMQ target.

process_dfe(ids: List[str]) → float

Process the results of a DFE protocol.

Parameters:

ids – A list (size two) of ids returned by a call to submit_dfe.

Returns:

The estimated fidelity between the two states as a float.

Raises:

  • ValueError – If ids is not of size two.

  • SuperstaqServerException – If there was an error accesing the API or the jobs submitted through submit_dfe have not finished running.

qscout_compile(circuits: qiskit.QuantumCircuit | Sequence[qiskit.QuantumCircuit], target: str = 'sandia_qscout_qpu', *, mirror_swaps: bool = False, base_entangling_gate: str = 'xx', num_qubits: int | None = None, error_rates: SupportsItems[tuple[int, ...], float] | None = None, **kwargs: Any) → qss.compiler_output.CompilerOutput

Compiles and optimizes the given circuit(s) for the QSCOUT trapped-ion testbed at Sandia National Laboratories [1].

Compiled circuits are returned as both qiskit.QuantumCircuit objects and corresponding Jaqal [2] programs (strings).

References

[1] S. M. Clark et al., *Engineering the Quantum Scientific Computing Open User

Testbed*, IEEE Transactions on Quantum Engineering Vol. 2, 3102832 (2021). https://doi.org/10.1109/TQE.2021.3096480.

[2] B. Morrison, et al., Just Another Quantum Assembly Language (Jaqal), 2020 IEEE

International Conference on Quantum Computing and Engineering (QCE), 402-408 (2020). https://arxiv.org/abs/2008.08042.

Parameters:

  • circuits – The circuit(s) to compile.

  • target – A string containing the name of a target backend.

  • mirror_swaps – Whether to use mirror swapping to reduce two-qubit gate overhead.

  • base_entangling_gate – The base entangling gate to use (“xx”, “zz”, “sxx”, or “szz”). Compilation with the “xx” and “zz” entangling bases will use arbitrary parameterized two-qubit interactions, while the “sxx” and “szz” bases will only use fixed maximally-entangling rotations.

  • num_qubits – An optional number of qubits that should be present in the compiled circuit(s) and Jaqal program(s) (otherwise this will be determined from the input).

  • error_rates – Optional dictionary assigning relative error rates to pairs of physical qubits, in the form {<qubit_indices>: <error_rate>, …} where <qubit_indices> is a tuple physical qubit indices (ints) and <error_rate> is a relative error rate for gates acting on those qubits (for example {(0, 1): 0.3, (1, 2): 0.2}) . If provided, Superstaq will attempt to map the circuit to minimize the total error on each qubit.

  • kwargs – Other desired qscout_compile options.

Returns:

Object whose .circuit(s) attribute contains optimized qiskit QuantumCircuit`(s), and `.jaqal_program(s) attribute contains the corresponding Jaqal program(s).

Raises:

  • ValueError – If target is not a valid Sandia target.

  • ValueError – If base_entangling_gate is not a valid gate option.

resource_estimate(circuits: QuantumCircuit | Sequence[QuantumCircuit], target: str) → ResourceEstimate | List[ResourceEstimate]

Generates resource estimates for qiskit circuit(s).

Parameters:

  • circuits – The circuit(s) used during resource estimation.

  • target – A string containing the name of a target backend.

Returns:

ResourceEstimate(s) containing resource costs (after compilation) for running circuit(s) on a backend.

submit_dfe(rho_1: Tuple[QuantumCircuit, str], rho_2: Tuple[QuantumCircuit, str], num_random_bases: int, shots: int, **kwargs: Any) → List[str]

Executes the circuits neccessary for the DFE protocol.

The circuits used to prepare the desired states should not contain final measurements, but can contain mid-circuit measurements (as long as the intended target supports them). For example, to prepare a Bell state to be ran in ss_unconstrained_simulator, you should pass qc = qiskit.QuantumCircuit(2); qc.h(0); qc.cx(0, 1) as the first element of some rho_i (note there are no final measurements).

The fidelity between states is calculated following the random measurement protocol outlined in [1].

References

[1] Elben, Andreas, Benoît Vermersch, Rick van Bijnen, Christian Kokail, Tiff Brydges,

Christine Maier, Manoj K. Joshi, Rainer Blatt, Christian F. Roos, and Peter Zoller. “Cross-platform verification of intermediate scale quantum devices.” Physical review letters 124, no. 1 (2020): 010504.

Parameters:

  • rho_1 – Tuple containing the information to prepare the first state. It contains a qiskit.QuantumCircuit at index 0 and a target name at index 1.

  • rho_2 – Tuple containing the information to prepare the second state. It contains a qiskit.QuantumCircuit at index 0 and a target name at index 1.

  • num_random_bases – Number of random bases to measure each state in.

  • shots – Number of shots to use per random basis.

  • kwargs – Other execution parameters. - tag: Tag for all jobs submitted for this protocol. - lifespan: How long to store the jobs submitted for in days (only works with right permissions). - method: Which type of method to execute the circuits with.

Returns:

A list with two strings, which are the job ids that need to be passed to process_dfe to post-process the measurement results and return the fidelity.

Raises:

  • ValueError – If circuit is not a valid qiskit.QuantumCircuit.

  • SuperstaqServerException – If there was an error accessing the API.

supercheq(files: List[List[int]], num_qubits: int, depth: int) → Tuple[List[QuantumCircuit], ndarray[Any, dtype[float64]]]

Returns Supercheq randomly generated circuits and the corresponding fidelity matrices.

References

[1] P. Gokhale et al., SupercheQ: Quantum Advantage for Distributed Databases, (2022).

https://arxiv.org/abs/2212.03850.

Parameters:

  • files – A list of files specified as binary using ints. For example: [[1, 0, 1], [1, 1, 1]].

  • num_qubits – The number of qubits to run Supercheq on.

  • depth – The depth of the circuits to run Supercheq on.

Returns:

A tuple containing a list of `qiskit.QuantumCircuit`s and a list of corresponding

fidelity matrices.

class qiskit_superstaq.ZZSwapGate(theta: float, label: str | None = None)

Bases: Gate

The ZZ-SWAP gate, which performs the ZZ-interaction followed by a SWAP.

ZZ-SWAPs are useful for applications like QAOA or Hamiltonian Simulation, particularly on linear- or low- connectivity devices. See https://arxiv.org/pdf/2004.14970.pdf for an application of ZZ-SWAP networks.

The unitary for a ZZ-SWAP gate parametrized by ZZ-interaction angle \(\theta\) is:

\[\begin{split}\begin{bmatrix} 1 & . & . & . \\ . & . & e^{i \theta} & . \\ . & e^{i \theta} & . & . \\ . & . & . & 1 \\ \end{bmatrix}\end{split}\]

where ‘.’ means ‘0’. For \(\theta = 0\), the ZZ-SWAP gate is just an ordinary SWAP.

inverse() → ZZSwapGate

Inverts the ZZ-SWAP gate.

Returns:

The inverse ZZ-SWAP gate.

qiskit_superstaq.active_qubit_indices(circuit: QuantumCircuit) → List[int]

Returns the indices of the non-idle qubits in the input quantum circuit.

Parameters:

circuit – A qiskit.QuantumCircuit circuit.

Returns:

A list containing the indices of the non-idle qubits.

qiskit_superstaq.deserialize_circuits(serialized_circuits: str) → List[QuantumCircuit]

Deserialize serialized `qiskit.QuantumCircuit`(s).

Parameters:

serialized_circuits – String generated via qss.serialization.serialize_circuit().

Returns:

A list containing the deserialized circuits.

Raises:

ValueError – If serialized_circuits can’t be deserialized.

qiskit_superstaq.measured_qubit_indices(circuit: QuantumCircuit) → List[int]

Returns the indices of the measured qubits in the input quantum circuit.

Parameters:

circuit – A qiskit.QuantumCircuit circuit.

Returns:

A list containing the indices of the measured qubits.

qiskit_superstaq.serialize_circuits(circuits: QuantumCircuit | Sequence[QuantumCircuit]) → str

Serialize QuantumCircuit(s) into a single string.

Parameters:

circuits – A qiskit.QuantumCircuit or list of `qiskit.QuantumCircuit`s to be serialized.

Returns:

A string representing the serialized circuit(s).