cirq_superstaq package

Subpackages

Submodules

cirq_superstaq.compiler_output module

class cirq_superstaq.compiler_output.CompilerOutput(circuits: cirq.Circuit | List[cirq.Circuit] | List[List[cirq.Circuit]], final_logical_to_physicals: Dict[cirq.Qid, cirq.Qid] | List[Dict[cirq.Qid, cirq.Qid]] | List[List[Dict[cirq.Qid, cirq.Qid]]], pulse_gate_circuits: Any | None = None, pulse_sequences: Any | None = None, seq: qtrl.sequencer.Sequence | None = None, jaqal_programs: List[str] | str | None = None, pulse_lists: List[List[List[Any]]] | List[List[List[List[Any]]]] | None = None)

Bases: object

A class that arranges compiled circuit information.

has_multiple_circuits() bool

Checks if an object has .circuits and .pulse_lists attributes.

Otherwise, the object represents a single circuit, and has .circuit and .pulse_list attributes.

Returns:

True if this object represents multiple circuits; False otherwise.

cirq_superstaq.compiler_output.active_qubit_indices(circuit: AbstractCircuit) List[int]

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

Note

The “index” refers to the argument of a LineQubit (so e.g. cirq.LineQubit(5) has index 5 regardless of the total number of qubits in the circuit.

Parameters:

circuit – The input quantum circuit.

Returns:

A list of active qubit indicies.

Raises:

ValueError – If qubit indices are requested for non-line qubits.

cirq_superstaq.compiler_output.measured_qubit_indices(circuit: AbstractCircuit) List[int]

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

Note

The “index” refers to the argument of a cirq.LineQubit (so e.g. cirq.LineQubit(5) has index 5 regardless of the total number of qubits in the circuit).

Parameters:

circuit – The input quantum circuit.

Returns:

A list of the measurement qubit indicies.

Raises:

ValueError – If qubit indices are requested for non-line qubits.

cirq_superstaq.compiler_output.read_json(json_dict: Dict[str, Any], circuits_is_list: bool) CompilerOutput

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

Parameters:
  • json_dict – A JSON dictionary matching the format returned by /ibmq_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). If included in the server response, the returned object also stores the corresponding pulse gate circuit(s) in its .pulse_gate_circuit(s) attribute, and pulse sequence(s) in its .pulse_sequences(s) attribute (provided qiskit-superstaq is available locally).

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

Reads out 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 – A bool flag that controls whether the returned object has a .circuits attribute (if True) or a .circuit attribute (False).

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

cirq_superstaq.compiler_output.read_json_qscout(json_dict: Dict[str, Any], circuits_is_list: bool) CompilerOutput

Reads out 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 – 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 a list of jaqal programs represented as strings.

cirq_superstaq.job module

Represents a job created via the Superstaq API.

class cirq_superstaq.job.Job(client: _SuperstaqClient, job_id: str)

Bases: object

A job created on the Superstaq API.

Note that this is mutable, when calls to get status or results are made the job updates itself to the results returned from the API.

If a job is canceled or deleted, only the job id and the status remain valid.

ALL_STATES = ('Done', 'Canceled', 'Failed', 'Deleted', 'Ready', 'Submitted', 'Running', 'Queued')
NON_TERMINAL_STATES = ('Ready', 'Submitted', 'Running', 'Queued')
TERMINAL_STATES = ('Done', 'Canceled', 'Failed', 'Deleted')
UNSUCCESSFUL_STATES = ('Canceled', 'Failed', 'Deleted')
compiled_circuits(index: int) Circuit
compiled_circuits(index: None = None) Circuit | List[Circuit]

Gets the compiled circuits that were processed for this job.

Parameters:

index – An optional index of the specific circuit to retrieve.

Returns:

A single compiled circuit or list of compiled circuits.

counts(index: int, timeout_seconds: int = 7200, polling_seconds: float = 1.0, qubit_indices: Sequence[int] | None = None) Dict[str, int]
counts(index: None = None, timeout_seconds: int = 7200, polling_seconds: float = 1.0, qubit_indices: Sequence[int] | None = None) Dict[str, int] | List[Dict[str, int]]

Polls the Superstaq API for counts results (frequency of each measurement outcome).

Parameters:
  • index – The index of the circuit which the counts correspond to.

  • timeout_seconds – The total number of seconds to poll for.

  • polling_seconds – The interval with which to poll.

  • qubit_indices – If provided, only include measurements counts of these qubits.

Returns:

A dictionary containing the frequency counts of the measurements.

Raises:
input_circuits(index: int) Circuit
input_circuits(index: None = None) Circuit | List[Circuit]

Gets the original circuits that were submitted for this job.

Parameters:

index – An optional index of the specific circuit to retrieve.

Returns:

A single input circuit or list of submitted input circuits.

job_id() str

Gets the job id of this job.

This is the unique identifier used for identifying the job by the API.

Returns:

This job’s id (a string).

num_qubits(index: int) int
num_qubits(index: None = None) int | List[int]

Gets the number of qubits required for each circuit in this job.

Parameters:

index – The index of the circuit to get number of qubits from.

Returns:

A list of the numbers of qubits in all circuits or just a single qubit number for the given circuit index.

Raises:
repetitions() int

Gets the number of repetitions requested for this job.

Returns:

The number of repetitions for this job.

Raises:
status() str

Gets the current status of the job.

If the current job is in a non-terminal state, this will update the job and return the current status. A full list of states is given in cirq_superstaq.Job.ALL_STATES.

Raises:

SuperstaqServerException – If unable to get the status of the job from the API.

Returns:

The job status.

target() str

Gets the Superstaq target associated with this job.

Returns:

The target to which this job was submitted.

Raises:
to_dict() Dict[str, Job]

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

cirq_superstaq.sampler module

A cirq.Sampler implementation for the Superstaq API.

class cirq_superstaq.sampler.Sampler(service: Service, target: str)

Bases: Sampler

A sampler that works against the Superstaq API. Users should get a sampler from the sampler method on css.Service.

Example:

service = css.Service(
    "Insert superstaq token that you received from https://superstaq.infleqtion.com"
    )
q0, q1 = cirq.LineQubit.range(2)
sampler = service.sampler("ibmq_qasm_simulator")
circuit = cirq.Circuit(cirq.H(q0), cirq.CNOT(q0, q1), cirq.measure(q0))
print(sampler.sample(circuit, repetitions=5))

    q(0)
0   0
1   0
2   0
3   1
4   1
run_sweep(program: AbstractCircuit, params: cirq.ParamResolver | Mapping[cirq.TParamKey, cirq.TParamValComplex] | None | Sweep | _Sweepable, repetitions: int = 1) List[ResultDict]

Runs a sweep for the given circuit.

Note

This creates jobs for each of the sweeps in the given sweepable, and then blocks until all of jobs are complete.

Parameters:
  • program – The circuit to sample from.

  • params – The parameters to run with program.

  • repetitions – The number of times to sample. Defaults to 1.

Returns:

A list of Cirq results, one for each parameter resolver.

run_sweep_async(program: cirq.AbstractCircuit, params: cirq.Sweepable, repetitions: int = 1) Sequence[cirq.Result]

Asynchronously samples from the given Circuit.

By default, this method invokes run_sweep synchronously and simply exposes its result is an awaitable. Child classes that are capable of true asynchronous sampling should override it to use other strategies.

Parameters:
  • program – The circuit to sample from.

  • params – Parameters to run with the program.

  • repetitions – The number of times to sample.

Returns:

Result list for this run; one for each possible parameter resolver.

cirq_superstaq.serialization module

cirq_superstaq.serialization.deserialize_circuits(serialized_circuits: str) List[Circuit]

Deserialize serialized circuit(s).

Parameters:

serialized_circuits – A json string generated via serialization.serialize_circuit().

Returns:

The circuit or list of circuits that was serialized.

cirq_superstaq.serialization.serialize_circuits(circuits: AbstractCircuit | Sequence[AbstractCircuit]) str

Serialize circuit(s) into a json string.

Parameters:

circuits – A cirq.Circuit or list of cirq.Circuits to be serialized.

Returns:

A string representing the serialized circuit(s).

cirq_superstaq.service module

Service to access Superstaqs API.

class cirq_superstaq.service.Service(api_key: str | None = None, remote_host: str | None = None, default_target: str | None = None, api_version: str = 'v0.2.0', 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, **kwargs: object)

Bases: 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: Circuit | Sequence[Circuit], target: str = 'aqt_keysight_qpu', *, num_eca_circuits: int | None = None, random_seed: int | None = None, atol: float | None = None, gate_defs: Mapping[str, ndarray[Any, dtype[complex128]] | Gate | Operation | 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 – 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.

  • 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: Circuit | Sequence[Circuit], num_equivalent_circuits: int, random_seed: int | None = None, target: str = 'aqt_keysight_qpu', atol: float | None = None, gate_defs: Mapping[str, ndarray[Any, dtype[complex128]] | Gate | Operation | None] | None = None, **kwargs: Any) 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, and its .pulse_list(s) attribute contains the corresponding list(s) of cycles.

Raises:

ValueError – If target is not a valid AQT target.

compile(circuits: Circuit | Sequence[Circuit], target: str, **kwargs: Any) 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: Circuit | Sequence[Circuit], 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 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 IBMQ target.

create_job(circuits: AbstractCircuit | Sequence[AbstractCircuit], repetitions: int = 1000, target: str | None = None, method: str | None = None, **kwargs: Any) Job

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.

  • kwargs – Other optimization and execution parameters.

Returns:

A css.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: Circuit, repetitions: int, target: str | None = None, param_resolver: cirq.ParamResolver | Mapping[cirq.TParamKey, cirq.TParamValComplex] | None = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) Dict[str, int]
get_counts(circuits: Sequence[Circuit], repetitions: int, target: str | None = None, param_resolver: cirq.ParamResolver | Mapping[cirq.TParamKey, cirq.TParamValComplex] | None = 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) Job

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

Raises:

SuperstaqServerException – If there was an error accessing the API.

ibmq_compile(circuits: Circuit | Sequence[Circuit], target: str = 'ibmq_qasm_simulator', dynamical_decoupling: bool = True, dd_strategy: str = 'static_context_aware', **kwargs: Any) 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.

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; either “dynamic”, “static”, or “static_context_aware” (default).

  • kwargs – Other desired ibmq_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.

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: cirq.Circuit | Sequence[cirq.Circuit], 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) css.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 Sandia target.

resource_estimate(circuits: Circuit | Sequence[Circuit], target: str | None = None) ResourceEstimate | List[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: Circuit, repetitions: int, target: str | None = None, param_resolver: ParamResolver = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) ResultDict
run(circuits: Sequence[Circuit], repetitions: int, target: str | None = None, param_resolver: ParamResolver = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) List[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) 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: Sequence[int], shots: int, num_circuits: int, mirror_depth: int, extra_depth: int, method: str | None = None, noise: str | NoiseModel | 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 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:
  • 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).

Returns:

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

Raises:
submit_dfe(rho_1: Tuple[AbstractCircuit, str], rho_2: Tuple[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:
  • ValueError – 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[Circuit], ndarray[Any, dtype[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.

cirq_superstaq.service.counts_to_results(counter: Mapping[str, float], circuit: AbstractCircuit, param_resolver: ParamResolver) 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.

cirq_superstaq.validation module

cirq_superstaq.validation.validate_cirq_circuits(circuits: object, require_measurements: bool = False) None

Validates that the input is either a single cirq.Circuit or a list of cirq.Circuit instances.

Parameters:
  • circuits – The circuit(s) to run.

  • require_measurements – An optional boolean flag to check if all of the circuits have measurements.

Raises:

ValueError – If the input is not a cirq.Circuit or a list of cirq.Circuit instances.

Module contents

class cirq_superstaq.AceCR(rads: str | float | Expr = 1.5707963267948966, sandwich_rx_rads: float | Expr = 0)

Bases: Gate

Active Cancellation Echoed Cross Resonance (AceCR) gate, parametrized (e.g., supporting polarity switches) and supporting sandwiches.

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

num_qubits() int

The number of qubits this gate acts on.

class cirq_superstaq.BSwapPowGate(*, exponent: float | Expr = 1.0, global_shift: float = 0.0)

Bases: EigenGate, InterchangeableQubitsGate

iSWAP-like qutrit entangling gate swapping the “11” and “22” states of two qutrits.

property dimension: int

Indicates that this gate acts on qutrits.

Returns:

The integer 3, representing the qudit dimension for qutrits.

num_qubits() int

The number of qubits this gate acts on.

class cirq_superstaq.Barrier(num_qubits: int | None = None, qid_shape: Tuple[int, ...] | None = None)

Bases: IdentityGate, InterchangeableQubitsGate

A temporal boundary restricting circuit compilation and pulse scheduling.

Otherwise equivalent to the identity gate.

class cirq_superstaq.Job(client: _SuperstaqClient, job_id: str)

Bases: object

A job created on the Superstaq API.

Note that this is mutable, when calls to get status or results are made the job updates itself to the results returned from the API.

If a job is canceled or deleted, only the job id and the status remain valid.

ALL_STATES = ('Done', 'Canceled', 'Failed', 'Deleted', 'Ready', 'Submitted', 'Running', 'Queued')
NON_TERMINAL_STATES = ('Ready', 'Submitted', 'Running', 'Queued')
TERMINAL_STATES = ('Done', 'Canceled', 'Failed', 'Deleted')
UNSUCCESSFUL_STATES = ('Canceled', 'Failed', 'Deleted')
compiled_circuits(index: int) Circuit
compiled_circuits(index: None = None) Circuit | List[Circuit]

Gets the compiled circuits that were processed for this job.

Parameters:

index – An optional index of the specific circuit to retrieve.

Returns:

A single compiled circuit or list of compiled circuits.

counts(index: int, timeout_seconds: int = 7200, polling_seconds: float = 1.0, qubit_indices: Sequence[int] | None = None) Dict[str, int]
counts(index: None = None, timeout_seconds: int = 7200, polling_seconds: float = 1.0, qubit_indices: Sequence[int] | None = None) Dict[str, int] | List[Dict[str, int]]

Polls the Superstaq API for counts results (frequency of each measurement outcome).

Parameters:
  • index – The index of the circuit which the counts correspond to.

  • timeout_seconds – The total number of seconds to poll for.

  • polling_seconds – The interval with which to poll.

  • qubit_indices – If provided, only include measurements counts of these qubits.

Returns:

A dictionary containing the frequency counts of the measurements.

Raises:
input_circuits(index: int) Circuit
input_circuits(index: None = None) Circuit | List[Circuit]

Gets the original circuits that were submitted for this job.

Parameters:

index – An optional index of the specific circuit to retrieve.

Returns:

A single input circuit or list of submitted input circuits.

job_id() str

Gets the job id of this job.

This is the unique identifier used for identifying the job by the API.

Returns:

This job’s id (a string).

num_qubits(index: int) int
num_qubits(index: None = None) int | List[int]

Gets the number of qubits required for each circuit in this job.

Parameters:

index – The index of the circuit to get number of qubits from.

Returns:

A list of the numbers of qubits in all circuits or just a single qubit number for the given circuit index.

Raises:
repetitions() int

Gets the number of repetitions requested for this job.

Returns:

The number of repetitions for this job.

Raises:
status() str

Gets the current status of the job.

If the current job is in a non-terminal state, this will update the job and return the current status. A full list of states is given in cirq_superstaq.Job.ALL_STATES.

Raises:

SuperstaqServerException – If unable to get the status of the job from the API.

Returns:

The job status.

target() str

Gets the Superstaq target associated with this job.

Returns:

The target to which this job was submitted.

Raises:
to_dict() Dict[str, Job]

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 Job 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 cirq_superstaq.ParallelGates(*component_gates: Gate)

Bases: Gate, InterchangeableQubitsGate

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

num_qubits() int

The number of qubits this gate acts on.

qubit_index_to_equivalence_group_key(index: int) int

Returns a key that differs between qubits.

Does it by different component gates and non-interchangeable qubits in the same component gate.

Parameters:

index – The qubit index.

Returns:

Equivalence group key.

qubit_index_to_gate_and_index(index: int) Tuple[Gate, int]

Gets gate (and index) for the corresponding index.

Parameters:

index – The index into a particular member of the ParallelGates operation.

Returns:

A tuple of the gate at the given index and the index itself.

Raises:

ValueError – If index is outside bounds of gate index range.

class cirq_superstaq.ParallelRGate(theta: float | Expr, phi: float | Expr, num_copies: int)

Bases: ParallelGate, InterchangeableQubitsGate

Wrapper class to define a ParallelGate of identical RGate gates.

property exponent: float | Expr

The exponent property of ParallelRGate.

Returns:

The sub gate exponent.

property phase_exponent: float | Expr

The phase_exponent property of each RGate.

Returns:

The phase exponent.

property phi: float | Expr

The phi property of ParallelRGate, defining orientation (i.e., axis of rotation).

Returns:

The rotation-axis angle phi.

property sub_gate: RGate

The gate that is applied to the specified subspace.

Returns:

The underlying gate used.

property theta: float | Expr

The theta property of ParallelRGate, angle to rotate about the phi-determined axis.

Returns:

The rotation angle theta.

class cirq_superstaq.QubitSubspaceGate(sub_gate: Gate, qid_shape: Sequence[int], subspaces: Sequence[Tuple[int, int]] | None = None)

Bases: Gate

Embeds an n-qubit (i.e. SU(2^n)) gate into a given subspace of a higher-dimensional gate.

num_qubits() int

The number of qubits this gate acts on.

property qid_shape: Tuple[int, ...]

Specifies the qudit dimension for each of the inputs.

Returns:

The dimensions for the input qudits.

property sub_gate: Gate

The gate that is applied to the specified subspace.

Returns:

The underlying gate used.

property subspaces: List[Tuple[int, int]]

A list of subspace indices acted upon.

For instance, a CX on the 0-1 qubit subspace of two qudits would have subspaces of [(0, 1), (0, 1)]. The same gate acting on the 1-2 subspaces of both qudits would correspond to [(1, 2), (1, 2)].

Returns:

A list of dimensions tuples, specified for each subspace.

class cirq_superstaq.QuditSwapGate(dimension: int)

Bases: Gate, InterchangeableQubitsGate

A (non-parametrized) SWAP gate on two qudits of arbitrary dimension.

property dimension: int

The qudit dimension on which this SWAP gate will act.

Returns:

The qudit dimension.

num_qubits() int

The number of qubits this gate acts on.

class cirq_superstaq.QutritCZPowGate(*, exponent: float | Expr = 1.0, global_shift: float = 0.0)

Bases: EigenGate, InterchangeableQubitsGate

For pairs of equal-dimension qudits, the generalized CZ gate is defined by the unitary:

U = Σ_(i<d,j<d) ω**ij.|i⟩⟨i|.|j⟩⟨j|,

where d is the dimension of the qudits and ω = exp(2πi/d).

Currently written for qutrits (d = 3), but its implementation should work for any dimension.

property dimension: int

Indicates that this gate acts on qutrits.

Returns:

The integer 3, representing the qudit dimension for qutrits.

num_qubits() int

The number of qubits this gate acts on.

class cirq_superstaq.QutritZ0PowGate(*, exponent: float | Expr = 1.0, global_shift: float = 0.0)

Bases: _QutritZPowGate

Phase rotation on the ground state of a qutrit.

num_qubits() int

The number of qubits this gate acts on.

class cirq_superstaq.QutritZ1PowGate(*, exponent: float | Expr = 1.0, global_shift: float = 0.0)

Bases: _QutritZPowGate

Phase rotation on the first excited state of a qutrit.

num_qubits() int

The number of qubits this gate acts on.

class cirq_superstaq.QutritZ2PowGate(*, exponent: float | Expr = 1.0, global_shift: float = 0.0)

Bases: _QutritZPowGate

Phase rotation on the second excited state of a qutrit.

num_qubits() int

The number of qubits this gate acts on.

class cirq_superstaq.RGate(theta: float | Expr, phi: float | Expr)

Bases: PhasedXPowGate

A single-qubit gate that rotates about an axis in the X-Y plane.

num_qubits() int

The number of qubits this gate acts on.

property phi: float | Expr

Angle (in radians) defining the axis of rotation in the X-Y plane.

Returns:

The phi rotation angle.

property theta: float | Expr

Angle (in radians) by which to rotate about the axis given by self.phi.

Returns:

The theta rotation angle.

class cirq_superstaq.Sampler(service: Service, target: str)

Bases: Sampler

A sampler that works against the Superstaq API. Users should get a sampler from the sampler method on css.Service.

Example:

service = css.Service(
    "Insert superstaq token that you received from https://superstaq.infleqtion.com"
    )
q0, q1 = cirq.LineQubit.range(2)
sampler = service.sampler("ibmq_qasm_simulator")
circuit = cirq.Circuit(cirq.H(q0), cirq.CNOT(q0, q1), cirq.measure(q0))
print(sampler.sample(circuit, repetitions=5))

    q(0)
0   0
1   0
2   0
3   1
4   1
run_sweep(program: AbstractCircuit, params: cirq.ParamResolver | Mapping[cirq.TParamKey, cirq.TParamValComplex] | None | Sweep | _Sweepable, repetitions: int = 1) List[ResultDict]

Runs a sweep for the given circuit.

Note

This creates jobs for each of the sweeps in the given sweepable, and then blocks until all of jobs are complete.

Parameters:
  • program – The circuit to sample from.

  • params – The parameters to run with program.

  • repetitions – The number of times to sample. Defaults to 1.

Returns:

A list of Cirq results, one for each parameter resolver.

run_sweep_async(program: cirq.AbstractCircuit, params: cirq.Sweepable, repetitions: int = 1) Sequence[cirq.Result]

Asynchronously samples from the given Circuit.

By default, this method invokes run_sweep synchronously and simply exposes its result is an awaitable. Child classes that are capable of true asynchronous sampling should override it to use other strategies.

Parameters:
  • program – The circuit to sample from.

  • params – Parameters to run with the program.

  • repetitions – The number of times to sample.

Returns:

Result list for this run; one for each possible parameter resolver.

class cirq_superstaq.Service(api_key: str | None = None, remote_host: str | None = None, default_target: str | None = None, api_version: str = 'v0.2.0', 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, **kwargs: object)

Bases: 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: Circuit | Sequence[Circuit], target: str = 'aqt_keysight_qpu', *, num_eca_circuits: int | None = None, random_seed: int | None = None, atol: float | None = None, gate_defs: Mapping[str, ndarray[Any, dtype[complex128]] | Gate | Operation | 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 – 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.

  • 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: Circuit | Sequence[Circuit], num_equivalent_circuits: int, random_seed: int | None = None, target: str = 'aqt_keysight_qpu', atol: float | None = None, gate_defs: Mapping[str, ndarray[Any, dtype[complex128]] | Gate | Operation | None] | None = None, **kwargs: Any) 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, and its .pulse_list(s) attribute contains the corresponding list(s) of cycles.

Raises:

ValueError – If target is not a valid AQT target.

compile(circuits: Circuit | Sequence[Circuit], target: str, **kwargs: Any) 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: Circuit | Sequence[Circuit], 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 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 IBMQ target.

create_job(circuits: AbstractCircuit | Sequence[AbstractCircuit], repetitions: int = 1000, target: str | None = None, method: str | None = None, **kwargs: Any) Job

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.

  • kwargs – Other optimization and execution parameters.

Returns:

A css.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: Circuit, repetitions: int, target: str | None = None, param_resolver: cirq.ParamResolver | Mapping[cirq.TParamKey, cirq.TParamValComplex] | None = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) Dict[str, int]
get_counts(circuits: Sequence[Circuit], repetitions: int, target: str | None = None, param_resolver: cirq.ParamResolver | Mapping[cirq.TParamKey, cirq.TParamValComplex] | None = 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) Job

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

Raises:

SuperstaqServerException – If there was an error accessing the API.

ibmq_compile(circuits: Circuit | Sequence[Circuit], target: str = 'ibmq_qasm_simulator', dynamical_decoupling: bool = True, dd_strategy: str = 'static_context_aware', **kwargs: Any) 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.

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; either “dynamic”, “static”, or “static_context_aware” (default).

  • kwargs – Other desired ibmq_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.

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: cirq.Circuit | Sequence[cirq.Circuit], 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) css.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 Sandia target.

resource_estimate(circuits: Circuit | Sequence[Circuit], target: str | None = None) ResourceEstimate | List[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: Circuit, repetitions: int, target: str | None = None, param_resolver: ParamResolver = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) ResultDict
run(circuits: Sequence[Circuit], repetitions: int, target: str | None = None, param_resolver: ParamResolver = cirq.ParamResolver({}), method: str | None = None, **kwargs: Any) List[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) 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: Sequence[int], shots: int, num_circuits: int, mirror_depth: int, extra_depth: int, method: str | None = None, noise: str | NoiseModel | 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 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:
  • 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).

Returns:

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

Raises:
submit_dfe(rho_1: Tuple[AbstractCircuit, str], rho_2: Tuple[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:
  • ValueError – 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[Circuit], ndarray[Any, dtype[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.

class cirq_superstaq.StrippedCZGate(rz_rads: float | Expr = 0)

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.

num_qubits() int

The number of qubits this gate acts on.

property rz_rads: float | Expr

The RZ-rotation angle in radians for the gate.

Returns:

The angle for the RZ rotation.

class cirq_superstaq.VirtualZPowGate(dimension: int = 2, level: int = 1, exponent: float | Expr = 1.0, global_shift: float = 0.0)

Bases: EigenGate

Applies a phase rotation between two successive energy levels of a qudit.

property dimension: int

The qudit dimension on which this gate acts.

property level: int

The lowest energy level onto which this gate applies a phase; for example if level=2 a phase of (-1)**exponent will be applied to energy levels [2, …, dimension - 1]. This is equivalent to phase shifting all subsequent single-qudit gates acting in the (1, 2) subspace (assuming all other gates commute with this one).

num_qubits() int

The number of qubits this gate acts on.

class cirq_superstaq.ZXPowGate(*, exponent: float | Expr = 1.0, global_shift: float = 0.0)

Bases: EigenGate, Gate

The ZX-parity gate, possibly raised to a power.

Per arxiv.org/pdf/1904.06560v3 eq. 135, the ZX**t gate implements the following unitary:

\[\begin{split}e^{-\frac{i\pi}{2} t Z \otimes X} = \begin{bmatrix} c & -s & . & . \\ -s & c & . & . \\ . & . & c & s \\ . & . & s & c \\ \end{bmatrix}\end{split}\]

where ‘.’ means ‘0’ and \(c = \cos(\frac{\pi t}{2})\) and \(s = i \sin(\frac{\pi t}{2})\).

num_qubits() int

The number of qubits this gate acts on.

class cirq_superstaq.ZZSwapGate(theta: float | Expr)

Bases: Gate, InterchangeableQubitsGate

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.

num_qubits() int

The number of qubits this gate acts on.

cirq_superstaq.active_qubit_indices(circuit: AbstractCircuit) List[int]

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

Note

The “index” refers to the argument of a LineQubit (so e.g. cirq.LineQubit(5) has index 5 regardless of the total number of qubits in the circuit.

Parameters:

circuit – The input quantum circuit.

Returns:

A list of active qubit indicies.

Raises:

ValueError – If qubit indices are requested for non-line qubits.

cirq_superstaq.approx_eq_mod(a: float | Expr, b: float | Expr, period: float, atol: float = 1e-08) bool

Check if a ~= b (mod period). If either input is an unresolved parameter, returns a == b.

Parameters:
  • a – A Cirq parameter value.

  • b – A Cirq parameter value.

  • period – The parameter period (i.e., cycle time).

  • atol – The absolute tolerance for equality checking.

Returns:

A boolean indicating whether input parameters are approximately equal.

cirq_superstaq.barrier(*qubits: Qid) Operation

Equivalent to https://qiskit.org/documentation/stubs/qiskit.circuit.library.Barrier.html.

Parameters:

qubits – The qubits that the barrier will cover.

Returns:

A barrier cirq.Operation on the provided qubits.

cirq_superstaq.deserialize_circuits(serialized_circuits: str) List[Circuit]

Deserialize serialized circuit(s).

Parameters:

serialized_circuits – A json string generated via serialization.serialize_circuit().

Returns:

The circuit or list of circuits that was serialized.

cirq_superstaq.measured_qubit_indices(circuit: AbstractCircuit) List[int]

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

Note

The “index” refers to the argument of a cirq.LineQubit (so e.g. cirq.LineQubit(5) has index 5 regardless of the total number of qubits in the circuit).

Parameters:

circuit – The input quantum circuit.

Returns:

A list of the measurement qubit indicies.

Raises:

ValueError – If qubit indices are requested for non-line qubits.

cirq_superstaq.parallel_gates_operation(*ops: Operation) Operation

Constructs a parallel gates operation.

Given operations acting on disjoint qubits, constructs a single css.ParallelGates instance and applies it such that each operation’s .gate is applied to its .qubits.

Parameters:

ops – Operations to pack into a single ParallelGates operation.

Returns:

ParallelGates(op.gate, op2.gate, …).on(*op.qubits, *op2.qubits, …)

Raises:
  • ValueError – If the operation has no .gate attribute.

  • ValueError – If the operation has tags.

cirq_superstaq.qubit_subspace_op(sub_op: Operation, qid_shape: Sequence[int], subspaces: Sequence[Tuple[int, int]] | None = None) Operation

Embeds a qubit Operation into a given subspace of a higher-dimensional Operation.

Uses QubitSubspaceGate.

Parameters:
  • sub_op – The cirq.Operation to embed.

  • qid_shape – The dimensions of the subspace.

  • subspaces – The list of all subspaces.

Returns:

A cirq.Operation embedding a low-dimensional operation.

Raises:

ValueError – If there is no gate specified for the subspace operation.

cirq_superstaq.qudit_swap_op(qudit0: Qid, qudit1: Qid) Operation

Construct a SWAP gate and apply it to the provided qudits.

If both qudits have dimension 2, uses cirq.SWAP; otherwise uses QuditSwapGate.

Parameters:
  • qudit0 – The first qudit to swap.

  • qudit1 – The second qudit to swap.

Returns:

A SWAP gate acting on the provided qudits.

Raises:

ValueError – If the input qudits don’t have the same dimension.

cirq_superstaq.serialize_circuits(circuits: AbstractCircuit | Sequence[AbstractCircuit]) str

Serialize circuit(s) into a json string.

Parameters:

circuits – A cirq.Circuit or list of cirq.Circuits to be serialized.

Returns:

A string representing the serialized circuit(s).