cirq_superstaq.service

Service to access Superstaqs API.

Classes

Service

A class to access Superstaq's API.

Functions

counts_to_results(→ cirq.ResultDict)

Converts a collections.Counter to a cirq.ResultDict.

Module Contents

class cirq_superstaq.service.Service(api_key: str | None = None, remote_host: str | None = None, default_target: str | None = None, api_version: str = gss.API_VERSION, max_retry_seconds: int = 3600, verbose: bool = False, cq_token: str | None = None, ibmq_token: str | None = None, ibmq_instance: str | None = None, ibmq_channel: str | None = None, use_stored_ibmq_credentials: bool = False, ibmq_name: str | None = None, **kwargs: object)

Bases: general_superstaq.service.Service

A class to access Superstaq’s API.

To access the API, this class requires a remote host url and an API key. These can be specified in the constructor via the parameters remote_host and api_key. Alternatively these can be specified by setting the environment variables SUPERSTAQ_REMOTE_HOST and SUPERSTAQ_API_KEY, or setting an API key in a configuration file.

aqt_compile(circuits: cirq.Circuit | collections.abc.Sequence[cirq.Circuit], target: str = 'aqt_keysight_qpu', *, num_eca_circuits: int | None = None, random_seed: int | None = None, atol: float | None = None, gate_defs: None | collections.abc.Mapping[str, numpy.typing.NDArray[numpy.number[Any]] | cirq.Gate | cirq.Operation | None] = None, gateset: collections.abc.Mapping[str, collections.abc.Sequence[collections.abc.Sequence[int]]] | None = None, pulses: object = None, variables: object = None, **kwargs: Any) → cirq_superstaq.compiler_output.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 – String of target AQT device.

  • 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 a unitary matrix, cirq.Gate, cirq.Operation, or None. More specific associations take precedence, for example {“SWAP”: cirq.SQRT_ISWAP, “SWAP/C5C4”: cirq.SQRT_ISWAP_INV} implies SQRT_ISWAP for all “SWAP” calibrations except “SWAP/C5C4” (which will instead be mapped to a SQRT_ISWAP_INV gate on qubits 4 and 5). Setting any calibration to None will disable that calibration.

  • gateset – Which gates to use for compilation. Should be a dictionary with entries in the for gate_name: [[1, 2], [3, 4], where the keys refer to specific gates, and the values indicate which qubit(s) they act upon.

  • pulses – Qtrl PulseManager or file path for pulse configuration.

  • variables – Qtrl VariableManager or file path for variable configuration.

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

Raises:

ValueError – If target is not a valid AQT target.

aqt_compile_eca(circuits: cirq.Circuit | collections.abc.Sequence[cirq.Circuit], num_equivalent_circuits: int, random_seed: int | None = None, target: str = 'aqt_keysight_qpu', atol: float | None = None, gate_defs: None | collections.abc.Mapping[str, numpy.typing.NDArray[numpy.number[Any]] | cirq.Gate | cirq.Operation | None] = None, **kwargs: Any) → cirq_superstaq.compiler_output.CompilerOutput

Compiles and optimizes the given circuit(s) for AQT using ECA.

The Advanced Quantum Testbed (AQT) is a superconducting transmon quantum computing testbed at Lawrence Berkeley National Laboratory. See arxiv.org/pdf/2111.04572.pdf for a description of Equivalent Circuit Averaging (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 – String of target AQT device.

  • 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 a unitary matrix, cirq.Gate, cirq.Operation, or None. More specific associations take precedence, for example {“SWAP”: cirq.SQRT_ISWAP, “SWAP/C5C4”: cirq.SQRT_ISWAP_INV} implies SQRT_ISWAP for all “SWAP” calibrations except “SWAP/C5C4” (which will instead be mapped to a SQRT_ISWAP_INV gate on 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.

Raises:

ValueError – If target is not a valid AQT target.

compile(circuits: cirq.Circuit | collections.abc.Sequence[cirq.Circuit], target: str, **kwargs: Any) → cirq_superstaq.compiler_output.CompilerOutput

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

Parameters:

  • circuits – The circuit(s) to compile.

  • target – String of target device.

  • kwargs – Other desired compile options.

Returns:

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

cq_compile(circuits: cirq.Circuit | collections.abc.Sequence[cirq.Circuit], target: str = 'cq_sqale_qpu', *, grid_shape: tuple[int, int] | None = None, control_radius: float = 1.0, stripped_cz_rads: float = 0.0, **kwargs: Any) → cirq_superstaq.compiler_output.CompilerOutput

Compiles and optimizes the given circuit(s) to the target CQ device.

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 contains the compiled cirq.Circuit(s).

Raises:

ValueError – If target is not a valid CQ target.

create_job(circuits: cirq.AbstractCircuit | collections.abc.Sequence[cirq.AbstractCircuit], repetitions: int = 1000, target: str | None = None, method: str | None = None, verbatim: bool = False, **kwargs: Any) → cirq_superstaq.Job | cirq_superstaq.JobV3

Creates a new job to run the given circuit(s).

Parameters:

  • circuits – The circuit or list of circuits to run.

  • repetitions – The number of times to repeat the circuit. Defaults to 1000.

  • target – Where to run the job.

  • method – The optional execution method.

  • verbatim – Run the provided circuit(s) verbatim (i.e. without compilation).

  • kwargs – Other optimization and execution parameters.

Returns:

A cirq_superstaq.Job which can be queried for status or results.

Raises:

  • ValueError – If there are no measurements in circuits.

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

get_counts(circuits: cirq.Circuit, repetitions: int, target: str | None = None, param_resolver: cirq.ParamResolverOrSimilarType = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) → dict[str, int]
get_counts(circuits: collections.abc.Sequence[cirq.Circuit], repetitions: int, target: str | None = None, param_resolver: cirq.ParamResolverOrSimilarType = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) → list[dict[str, int]]

Runs circuit(s) on the Superstaq API and returns the result(s) as a dict.

Parameters:

  • circuits – The circuit(s) to run.

  • repetitions – The number of times to run the circuit(s).

  • target – Where to run the job.

  • param_resolver – A cirq.ParamResolver to resolve parameters in circuits.

  • method – Optional execution method.

  • kwargs – Other optimization and execution parameters.

Returns:

The counts from running the circuit(s).

get_job(job_id: str | uuid.UUID) → cirq_superstaq.Job | cirq_superstaq.JobV3

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 cirq_superstaq.Job which can be queried for status or results.

Raises:

SuperstaqServerException – If there was an error accessing the API.

ibmq_compile(circuits: cirq.Circuit | collections.abc.Sequence[cirq.Circuit], target: str, *, dynamical_decoupling: bool = True, dd_strategy: str = 'adaptive', **kwargs: Any) → cirq_superstaq.compiler_output.CompilerOutput

Compiles and optimizes the given circuit(s) to the target IBMQ device.

Qiskit Terra must be installed to correctly deserialize pulse schedules for pulse-enabled targets.

Superstaq currently supports the following dynamical decoupling strategies:

  • “standard”: Places a single DD sequence in each idle window.

  • “syncopated”: Places DD pulses at fixed time intervals, alternating between pulses on

    neighboring qubits in order to mitigate parasitic ZZ coupling errors.

  • “adaptive” (default): Dynamically spaces DD pulses across idle windows with awareness of

    neighboring qubits to achieve the parasitic ZZ coupling mitigation of the “syncopated” strategy with fewer pulses and less discretization error.

See https://superstaq.readthedocs.io/en/latest/optimizations/ibm/ibmq_dd_strategies_qiskit_superstaq.html for an example of each strategy.

Parameters:

  • circuits – The circuit(s) to compile.

  • target – String of target IBMQ device.

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

  • dd_strategy – Method to use for placing dynamical decoupling operations; should be either “standard”, “syncopated”, or “adaptive” (default). See above.

  • kwargs – Other desired compile options.

Returns:

Object whose .circuit(s) attribute contains the compiled cirq.Circuit(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.

plot(circuits_and_metadata: dict[str, Any]) → None

Generates plot and fit data estimating decay parameters.

Parameters:

circuits_and_metadata – Dictionary containing cycle benchmarking data.

process_cb(job_id: str, counts: list[dict[str, int]] | None = None) → dict[str, Any]

Processes the data from the Cycle Benchmarking protocol. Generates SPAM and decay parameter estimations in addition to the process infidelity.

Parameters:

  • job_id – String corresponding to the CB job id.

  • counts – Optional list of dictionaries containing results counts to

compute fidelities for.

Returns:

A dict containing the Cycle Benchmarking process data.

Raises:

SuperstaqServerException – If the request fails.

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 accessing the API or the jobs submitted through submit_dfe have not finished running.

qscout_compile(circuits: cirq.Circuit | collections.abc.Sequence[cirq.Circuit], target: str = 'qscout_peregrine_qpu', *, mirror_swaps: bool = False, base_entangling_gate: str = 'xx', num_qubits: int | None = None, error_rates: _typeshed.SupportsItems[tuple[int, Ellipsis], float] | None = None, **kwargs: Any) → cirq_superstaq.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 cirq.Circuit 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 – String of target representing target device.

  • 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 initialized in the returned Jaqal program(s) (by default this will be determined from the input circuits).

  • 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. Omitted qubit pairs are assumed to be error-free.

  • kwargs – Other desired qscout_compile options.

Returns:

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

Raises:

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

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

resource_estimate(circuits: cirq.Circuit | collections.abc.Sequence[cirq.Circuit], target: str | None = None) → general_superstaq.ResourceEstimate | list[general_superstaq.ResourceEstimate]

Generates resource estimates for circuit(s).

Parameters:

  • circuits – The circuit(s) to generate resource estimate.

  • target – String of target representing target device.

Returns:

ResourceEstimate(s) containing resource costs (after compilation).

run(circuits: cirq.Circuit, repetitions: int, target: str | None = None, param_resolver: cirq.ParamResolver = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) → cirq.ResultDict
run(circuits: collections.abc.Sequence[cirq.Circuit], repetitions: int, target: str | None = None, param_resolver: cirq.ParamResolver = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) → list[cirq.ResultDict]

Runs circuit(s) on the Superstaq API and returns the result(s) as cirq.ResultDict.

WARNING: This may return unexpected results when used with measurement error mitigation. Use service.create_job() or service.get_counts() instead.

Parameters:

  • circuits – The circuit(s) to run.

  • repetitions – The number of times to run the circuit(s).

  • target – Where to run the job.

  • param_resolver – A cirq.ParamResolver to resolve parameters in circuits.

  • method – Execution method.

  • kwargs – Other optimization and execution parameters.

Returns:

The cirq.ResultDict object(s) from running the circuit(s).

sampler(target: str | None = None) → cirq.Sampler

Returns a cirq.Sampler object for accessing sampler interface.

Parameters:

target – Target to sample against.

Returns:

A cirq.Sampler for the Superstaq API.

submit_aces(target: str, qubits: collections.abc.Sequence[int], shots: int, num_circuits: int, mirror_depth: int, extra_depth: int, method: str | None = None, noise: str | cirq.NoiseModel | None = None, error_prob: float | tuple[float, float, float] | None = None, tag: str | None = None, lifespan: int | None = None, weights: collections.abc.Iterable[int] | None = None) → str

Submits the jobs to characterize target through the ACES protocol.

The following gate eigenvalues are estimated. 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:

  • target – The device target to characterize.

  • 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. It can be either a string or a cirq.NoiseModel. 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).

  • weights – Valid Pauli string weights for probes.

Returns:

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

Raises:
submit_cb(repetitions: int, process_circuit: cirq.Circuit, target: str, n_channels: int, n_sequences: int, depths: collections.abc.Sequence[int], method: str | None = None, noise: str | cirq.NoiseModel | None = None, error_prob: float | tuple[float, float, float] | None = None) → str

Submits the jobs to characterize target through the Cycle Benchmarking protocol.

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

Parameters:

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

  • process_circuit – The process circuit to use in the protocol.

  • target – The target device to characterize.

  • n_channels – The number of random Pauli decay channels to approximate error.

  • n_sequences – Number of circuits to generate per depth.

  • depths – Lists of depths representing the depths of Cycle Benchmarking circuits to generate.

  • method – Optional method to use in device submission (e.g. “dry-run”).

  • noise – Noise model to simulate the protocol with. It can be either a string or a cirq.NoiseModel. 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.

Returns:

A string with the job id for the Cycle Benchmarking job created.

Raises:
submit_dfe(rho_1: tuple[cirq.AbstractCircuit, str], rho_2: tuple[cirq.AbstractCircuit, 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 cirq.Circuit(cirq.H(qubits[0]), cirq.CX(qubits[0], qubits[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 cirq.Circuit at index 0 and a target name at index 1.

  • rho_2 – Tuple containing the information to prepare the second state. It contains a cirq.Circuit 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:

  • TypeError – If circuit is not a valid cirq.Circuit.

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

supercheq(files: list[list[int]], num_qubits: int, depth: int) → tuple[list[cirq.Circuit], numpy.typing.NDArray[numpy.float64]]

Returns the randomly generated circuits and the fidelity matrix for inputted files.

Parameters:

  • files – Input files from which to generate random circuits and fidelity matrix.

  • num_qubits – The number of qubits to use to generate random circuits.

  • depth – The depth of the random circuits to generate.

Returns:

A tuple containing the generated circuits and the fidelities for distinguishing files.

target_info(target: str) → dict[str, Any]

Returns information about device specified by target.

Parameters:

target – A string corresponding to a device.

Returns:

The corresponding device information.

default_target = None
cirq_superstaq.service.counts_to_results(counter: collections.abc.Mapping[str, float], circuit: cirq.AbstractCircuit, param_resolver: cirq.ParamResolver) → cirq.ResultDict

Converts a collections.Counter to a cirq.ResultDict.

Parameters:

  • counter – The collections.Counter of counts for the run.

  • circuit – The circuit to run.

  • param_resolver – A cirq.ParamResolver to resolve parameters in circuit.

Returns:

A cirq.ResultDict for the given circuit and counter.