cirq_superstaq.service ====================== .. py:module:: cirq_superstaq.service .. autoapi-nested-parse:: Service to access Superstaqs API. Classes ------- .. autoapisummary:: cirq_superstaq.service.Service Functions --------- .. autoapisummary:: cirq_superstaq.service.counts_to_results Module Contents --------------- .. py:class:: 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: :py:obj:`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. .. py:method:: 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. :param circuits: The circuit(s) to compile. :param target: String of target AQT device. :param num_eca_circuits: Optional number of logically equivalent random circuits to generate from each input circuit for Equivalent Circuit Averaging (ECA). :param random_seed: Optional seed used for approximate synthesis and ECA. :param atol: An optional tolerance to use for approximate gate synthesis. :param 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. :param 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. :param pulses: Qtrl `PulseManager` or file path for pulse configuration. :param variables: Qtrl `VariableManager` or file path for variable configuration. :param 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. .. py:method:: 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()`. :param circuits: The circuit(s) to compile. :param num_equivalent_circuits: Number of logically equivalent random circuits to generate for each input circuit. :param random_seed: Optional seed for circuit randomizer. :param target: String of target AQT device. :param atol: An optional tolerance to use for approximate gate synthesis. :param 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. :param 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. .. py:method:: 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. :param circuits: The circuit(s) to compile. :param target: String of target device. :param kwargs: Other desired compile options. :returns: A `CompilerOutput` object whose .circuit(s) attribute contains optimized compiled circuit(s). .. py:method:: 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. :param circuits: The circuit(s) to compile. :param target: String of target CQ device. :param grid_shape: Optional fixed dimensions for the rectangular qubit grid (by default the actual qubit layout will be pulled from the hardware provider). :param control_radius: The radius with which qubits remain connected (ie 1.0 indicates nearest neighbor connectivity). :param stripped_cz_rads: The angle in radians of the stripped cz gate. :param 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. .. py:method:: create_job(circuits: cirq.AbstractCircuit | collections.abc.Sequence[cirq.AbstractCircuit], repetitions: int = 1000, target: str | None = None, method: str | None = None, verbatim: bool = False, tag: collections.abc.Sequence[str] | str = (), metadata: collections.abc.Mapping[str, object] | None = None, **kwargs: Any) -> cirq_superstaq.Job | cirq_superstaq.JobV3 Creates a new job to run the given circuit(s). :param circuits: The circuit or list of circuits to run. :param repetitions: The number of times to repeat the circuit. Defaults to 1000. :param target: Where to run the job. :param method: The optional execution method. :param verbatim: Run the provided circuit(s) verbatim (i.e. without compilation). :param tag: An identifying tag (or list of tags) which can be used to find this job. :param metadata: Other data to store alongside the job. :param 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`. :raises ~general_superstaq.SuperstaqServerException: If there was an error accessing the API. .. py:method:: 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`. :param circuits: The circuit(s) to run. :param repetitions: The number of times to run the circuit(s). :param target: Where to run the job. :param param_resolver: A `cirq.ParamResolver` to resolve parameters in `circuits`. :param method: Optional execution method. :param kwargs: Other optimization and execution parameters. :returns: The counts from running the circuit(s). .. py:method:: get_job(job_id: str | uuid.UUID) -> cirq_superstaq.Job | cirq_superstaq.JobV3 Gets a job that has been created on the Superstaq API. :param job_id: The UUID of the job. Jobs are assigned these numbers by the server during the :param creation of the job.: :returns: A `cirq_superstaq.Job` which can be queried for status or results. :raises ~general_superstaq.SuperstaqServerException: If there was an error accessing the API. .. py:method:: 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. :param circuits: The circuit(s) to compile. :param target: String of target IBMQ device. :param dynamical_decoupling: Applies dynamical decoupling optimization to circuit(s). :param dd_strategy: Method to use for placing dynamical decoupling operations; should be either "standard", "syncopated", or "adaptive" (default). See above. :param 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. .. py:method:: plot(circuits_and_metadata: dict[str, Any]) -> None Generates plot and fit data estimating decay parameters. :param circuits_and_metadata: Dictionary containing cycle benchmarking data. .. py:method:: 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. :param job_id: String corresponding to the CB job id. :param counts: Optional list of dictionaries containing results counts to compute fidelities for. :returns: A dict containing the Cycle Benchmarking process data. :raises ~general_superstaq.SuperstaqServerException: If the request fails. .. py:method:: process_dfe(ids: list[str]) -> float Process the results of a DFE protocol. :param 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. :raises ~general_superstaq.SuperstaqServerException: If there was an error accessing the API or the jobs submitted through `submit_dfe` have not finished running. .. py:method:: 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). .. rubric:: 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. :param circuits: The circuit(s) to compile. :param target: String of target representing target device. :param mirror_swaps: Whether to use mirror swapping to reduce two-qubit gate overhead. :param 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. :param 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). :param error_rates: Optional dictionary assigning relative error rates to pairs of physical qubits, in the form `{: , ...}` where `` is a tuple physical qubit indices (ints) and `` 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. :param 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. :raises ValueError: If `target` is not a valid QSCOUT target. .. py:method:: 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). :param circuits: The circuit(s) to generate resource estimate. :param target: String of target representing target device. :returns: ResourceEstimate(s) containing resource costs (after compilation). .. py:method:: 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. :param circuits: The circuit(s) to run. :param repetitions: The number of times to run the circuit(s). :param target: Where to run the job. :param param_resolver: A `cirq.ParamResolver` to resolve parameters in `circuits`. :param method: Execution method. :param kwargs: Other optimization and execution parameters. :returns: The `cirq.ResultDict` object(s) from running the circuit(s). .. py:method:: sampler(target: str | None = None) -> cirq.Sampler Returns a `cirq.Sampler` object for accessing sampler interface. :param target: Target to sample against. :returns: A `cirq.Sampler` for the Superstaq API. .. py:method:: 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. :param target: The device target to characterize. :param qubits: A list with the qubit indices to characterize. :param shots: How many shots to use per circuit submitted. :param num_circuits: How many random circuits to use in the protocol. :param mirror_depth: The half-depth of the mirror portion of the random circuits. :param extra_depth: The depth of the fully random portion of the random circuits. :param method: Which type of method to execute the circuits with. :param 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". :param 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`. :param tag: Tag for all jobs submitted for this protocol. :param lifespan: How long to store the jobs submitted for in days (only works with right permissions). :param weights: Valid Pauli string weights for probes. :returns: A string with the job id for the ACES job created. :raises ValueError: If the target or noise model is not valid. :raises ~general_superstaq.SuperstaqServerException: If the request fails. .. py:method:: 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. :param repetitions: How many shots to use per circuit submitted. :param process_circuit: The process circuit to use in the protocol. :param target: The target device to characterize. :param n_channels: The number of random Pauli decay channels to approximate error. :param n_sequences: Number of circuits to generate per depth. :param depths: Lists of depths representing the depths of Cycle Benchmarking circuits to generate. :param method: Optional method to use in device submission (e.g. "dry-run"). :param 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". :param 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 ValueError: If the target or noise model is not valid. :raises ~general_superstaq.SuperstaqServerException: If the request fails. .. py:method:: 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]. .. rubric:: 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. :param 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. :param 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. :param num_random_bases: Number of random bases to measure each state in. :param shots: Number of shots to use per random basis. :param 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`. :raises ~general_superstaq.SuperstaqServerException: If there was an error accessing the API. .. py:method:: 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. :param files: Input files from which to generate random circuits and fidelity matrix. :param num_qubits: The number of qubits to use to generate random circuits. :param depth: The depth of the random circuits to generate. :returns: A tuple containing the generated circuits and the fidelities for distinguishing files. .. py:method:: target_info(target: str) -> dict[str, Any] Returns information about device specified by `target`. :param target: A string corresponding to a device. :returns: The corresponding device information. .. py:attribute:: default_target :value: None .. py:function:: 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`. :param counter: The `collections.Counter` of counts for the run. :param circuit: The circuit to run. :param param_resolver: A `cirq.ParamResolver` to resolve parameters in `circuit`. :returns: A `cirq.ResultDict` for the given circuit and counter.