cirq_superstaq ============== .. py:module:: cirq_superstaq Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/cirq_superstaq/compiler_output/index /autoapi/cirq_superstaq/job/index /autoapi/cirq_superstaq/ops/index /autoapi/cirq_superstaq/sampler/index /autoapi/cirq_superstaq/serialization/index /autoapi/cirq_superstaq/service/index /autoapi/cirq_superstaq/validation/index Attributes ---------- .. autoapisummary:: cirq_superstaq.AQTICCX cirq_superstaq.AQTITOFFOLI cirq_superstaq.AceCRMinusPlus cirq_superstaq.AceCRPlusMinus cirq_superstaq.BSWAP cirq_superstaq.BSWAP_INV cirq_superstaq.CR cirq_superstaq.CZ3 cirq_superstaq.CZ3_INV cirq_superstaq.DD cirq_superstaq.QutritZ0 cirq_superstaq.QutritZ1 cirq_superstaq.QutritZ2 cirq_superstaq.SUPERSTAQ_RESOLVERS cirq_superstaq.SWAP3 cirq_superstaq.ZX Classes ------- .. autoapisummary:: cirq_superstaq.AceCR cirq_superstaq.BSwapPowGate cirq_superstaq.Barrier cirq_superstaq.DDPowGate cirq_superstaq.Job cirq_superstaq.ParallelGates cirq_superstaq.ParallelRGate cirq_superstaq.QubitSubspaceGate cirq_superstaq.QuditSwapGate cirq_superstaq.QutritCZPowGate cirq_superstaq.QutritZ0PowGate cirq_superstaq.QutritZ1PowGate cirq_superstaq.QutritZ2PowGate cirq_superstaq.RGate cirq_superstaq.Sampler cirq_superstaq.Service cirq_superstaq.StrippedCZGate cirq_superstaq.VirtualZPowGate cirq_superstaq.ZXPowGate cirq_superstaq.ZZSwapGate Functions --------- .. autoapisummary:: cirq_superstaq.active_qubit_indices cirq_superstaq.approx_eq_mod cirq_superstaq.barrier cirq_superstaq.deserialize_circuits cirq_superstaq.measured_qubit_indices cirq_superstaq.parallel_gates_operation cirq_superstaq.qubit_subspace_op cirq_superstaq.qudit_swap_op cirq_superstaq.serialize_circuits Package Contents ---------------- .. py:class:: AceCR(rads: str | cirq.TParamVal = np.pi / 2, sandwich_rx_rads: cirq.TParamVal = 0) Bases: :py:obj:`cirq.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). .. py:attribute:: rads .. py:attribute:: sandwich_rx_rads :value: 0 .. py:class:: BSwapPowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0) Bases: :py:obj:`cirq.EigenGate`, :py:obj:`cirq.InterchangeableQubitsGate` iSWAP-like qutrit entangling gate swapping the "11" and "22" states of two qutrits. .. py:property:: dimension :type: int Indicates that this gate acts on qutrits. :returns: The integer `3`, representing the qudit dimension for qutrits. .. py:class:: Barrier(num_qubits: Optional[int] = None, qid_shape: Optional[Tuple[int, Ellipsis]] = None) Bases: :py:obj:`cirq.ops.IdentityGate`, :py:obj:`cirq.InterchangeableQubitsGate` A temporal boundary restricting circuit compilation and pulse scheduling. Otherwise equivalent to the identity gate. .. py:class:: DDPowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0) Bases: :py:obj:`cirq.EigenGate` The Dipole-Dipole gate for EeroQ hardware .. py:class:: Job(client: general_superstaq.superstaq_client._SuperstaqClient, job_id: str) 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. .. py:method:: cancel(index: int | None = None, **kwargs: object) -> None Cancel the current job if it is not in a terminal state. :param index: An optional index of the specific sub-job to cancel. :param kwargs: Extra options needed to fetch jobs. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API or cancellations were unsuccessful. .. py:method:: compiled_circuits(index: int) -> cirq.Circuit compiled_circuits(index: None = None) -> list[cirq.Circuit] Gets the compiled circuits that were processed for this job. :param index: An optional index of the specific circuit to retrieve. :returns: A single compiled circuit or list of compiled circuits. .. py:method:: counts(index: int, timeout_seconds: int = 7200, polling_seconds: float = 1.0, qubit_indices: collections.abc.Sequence[int] | None = None) -> dict[str, int] counts(index: None = None, timeout_seconds: int = 7200, polling_seconds: float = 1.0, qubit_indices: collections.abc.Sequence[int] | None = None) -> list[dict[str, int]] Polls the Superstaq API for counts results (frequency of each measurement outcome). :param index: The index of the circuit which the counts correspond to. :param timeout_seconds: The total number of seconds to poll for. :param polling_seconds: The interval with which to poll. :param qubit_indices: If provided, only include measurements counts of these qubits. :returns: A dictionary containing the frequency counts of the measurements the job indexed by `index` or a list of such dictionaries for each respective sub-job. :raises ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the results from the API. :raises TimeoutError: If no results are available in the provided timeout interval. .. py:method:: input_circuits(index: int) -> cirq.Circuit input_circuits(index: None = None) -> list[cirq.Circuit] Gets the original circuits that were submitted for this job. :param index: An optional index of the specific circuit to retrieve. :returns: A single input circuit or list of submitted input circuits. .. py:method:: 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). .. py:method:: num_qubits(index: int) -> int num_qubits(index: None = None) -> list[int] Gets the number of qubits required for each circuit in this job. :param 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 ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API. .. py:method:: pulse_gate_circuits(index: int | None = None) -> Any Gets the pulse gate circuit(s) returned by this job. :param index: An optional index of the pulse gate circuit to retrieve. :returns: A `qiskit.QuantumCircuit` pulse gate circuit or list of `qiskit.QuantumCircuit` pulse gate circuits. :raises ValueError: If the job was not run on an IBM pulse device. :raises ValueError: If the job's target does not use pulse gate circuits. .. py:method:: repetitions() -> int Gets the number of repetitions requested for this job. :returns: The number of repetitions for this job. :raises ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API. .. py:method:: status(index: int | None = None) -> 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`. :param index: An optional index of the specific sub-job to cancel. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API. :returns: The status of the job indexed by `index` or the overall job status if `index` is `None`. .. py:method:: target() -> str Gets the Superstaq target associated with this job. :returns: The target to which this job was submitted. :raises ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API. .. py:method:: to_dict() -> dict[str, general_superstaq.typing.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. .. py:attribute:: ALL_STATES :value: ('Done', 'Canceled', 'Failed', 'Deleted', 'Ready', 'Submitted', 'Running', 'Queued') .. py:attribute:: NON_TERMINAL_STATES :value: ('Ready', 'Submitted', 'Running', 'Queued') .. py:attribute:: TERMINAL_STATES :value: ('Done', 'Canceled', 'Failed', 'Deleted') .. py:attribute:: UNSUCCESSFUL_STATES :value: ('Canceled', 'Failed', 'Deleted') .. py:class:: ParallelGates(*component_gates: cirq.Gate) Bases: :py:obj:`cirq.Gate`, :py:obj:`cirq.InterchangeableQubitsGate` A single gate combining a collection of concurrent gate(s) acting on different qubits. .. py:method:: 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. :param index: The qubit index. :returns: Equivalence group key. .. py:method:: qubit_index_to_gate_and_index(index: int) -> tuple[cirq.Gate, int] Gets gate (and index) for the corresponding index. :param 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. .. py:attribute:: component_gates :type: tuple[cirq.Gate, Ellipsis] :value: () .. py:class:: ParallelRGate(theta: cirq.TParamVal, phi: cirq.TParamVal, num_copies: int) Bases: :py:obj:`cirq.ParallelGate`, :py:obj:`cirq.InterchangeableQubitsGate` Wrapper class to define a ParallelGate of identical RGate gates. .. py:property:: exponent :type: cirq.TParamVal The `exponent` property of `ParallelRGate`. :returns: The sub gate exponent. .. py:property:: phase_exponent :type: cirq.TParamVal The `phase_exponent` property of each `RGate`. :returns: The phase exponent. .. py:property:: phi :type: cirq.TParamVal The `phi` property of `ParallelRGate`, defining orientation (i.e., axis of rotation). :returns: The rotation-axis angle phi. .. py:property:: sub_gate :type: RGate The gate that is applied to the specified subspace. :returns: The underlying gate used. .. py:property:: theta :type: cirq.TParamVal The `theta` property of `ParallelRGate`, angle to rotate about the phi-determined axis. :returns: The rotation angle theta. .. py:class:: QubitSubspaceGate(sub_gate: cirq.Gate, qid_shape: collections.abc.Sequence[int], subspaces: collections.abc.Sequence[tuple[int, int]] | None = None) Bases: :py:obj:`cirq.Gate` Embeds an n-qubit (i.e. SU(2^n)) gate into a given subspace of a higher-dimensional gate. .. py:property:: qid_shape :type: tuple[int, Ellipsis] Specifies the qudit dimension for each of the inputs. :returns: The dimensions for the input qudits. .. py:property:: sub_gate :type: cirq.Gate The gate that is applied to the specified subspace. :returns: The underlying gate used. .. py:property:: subspaces :type: 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. .. py:class:: QuditSwapGate(dimension: int) Bases: :py:obj:`cirq.Gate`, :py:obj:`cirq.InterchangeableQubitsGate` A (non-parametrized) SWAP gate on two qudits of arbitrary dimension. .. py:property:: dimension :type: int The qudit dimension on which this SWAP gate will act. :returns: The qudit dimension. .. py:class:: QutritCZPowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0) Bases: :py:obj:`cirq.EigenGate`, :py:obj:`cirq.InterchangeableQubitsGate` For pairs of equal-dimension qudits, the generalized CZ gate is defined by the unitary: U = Σ_(i list[cirq.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. :param program: The circuit to sample from. :param params: The parameters to run with program. :param repetitions: The number of times to sample. Defaults to 1. :returns: A list of Cirq results, one for each parameter resolver. .. 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, **kwargs: Any) -> cirq_superstaq.job.Job 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 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) -> cirq_superstaq.job.Job 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 ValueError: 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:class:: StrippedCZGate(rz_rads: cirq.TParamVal = 0) Bases: :py:obj:`cirq.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 Sqale, and it is corrected into a CZ gate by RZ gates afterwards if the rz angle is nonzero. .. py:property:: rz_rads :type: cirq.TParamVal The RZ-rotation angle in radians for the gate. :returns: The angle for the RZ rotation. .. py:class:: VirtualZPowGate(dimension: int = 2, level: int = 1, exponent: cirq.TParamVal = 1.0, global_shift: float = 0.0) Bases: :py:obj:`cirq.EigenGate` Applies a phase rotation between two successive energy levels of a qudit. .. py:property:: dimension :type: int The qudit dimension on which this gate acts. :returns: The gate's dimension. .. py:property:: level :type: 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). :returns: The lowest energy level onto which this gate applies a phase. .. py:class:: ZXPowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0) Bases: :py:obj:`cirq.EigenGate` 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: .. math:: e^{-\frac{i\pi}{2} t Z \otimes X} = \begin{bmatrix} c & -s & . & . \\ -s & c & . & . \\ . & . & c & s \\ . & . & s & c \\ \end{bmatrix} where '.' means '0' and :math:`c = \cos(\frac{\pi t}{2})` and :math:`s = i \sin(\frac{\pi t}{2})`. .. py:class:: ZZSwapGate(theta: cirq.TParamVal) Bases: :py:obj:`cirq.Gate`, :py:obj:`cirq.ops.gate_features.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 :math:`\theta` is: .. math:: \begin{bmatrix} 1 & . & . & . \\ . & . & e^{i \theta} & . \\ . & e^{i \theta} & . & . \\ . & . & . & 1 \\ \end{bmatrix} where '.' means '0'. For :math:`\theta = 0`, the ZZ-SWAP gate is just an ordinary SWAP. .. py:attribute:: theta .. py:function:: active_qubit_indices(circuit: cirq.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). :param circuit: The input quantum circuit. :returns: A list of active qubit indicies. :raises ValueError: If qubit indices are requested for non-line qubits. .. py:function:: approx_eq_mod(a: cirq.TParamVal, b: cirq.TParamVal, period: float, atol: float = 1e-08) -> bool Check if a ~= b (mod period). If either input is an unresolved parameter, returns a == b. :param a: A Cirq parameter value. :param b: A Cirq parameter value. :param period: The parameter period (i.e., cycle time). :param atol: The absolute tolerance for equality checking. :returns: A boolean indicating whether input parameters are approximately equal. .. py:function:: barrier(*qubits: cirq.Qid) -> cirq.Operation Equivalent to https://qiskit.org/documentation/stubs/qiskit.circuit.library.Barrier.html. :param qubits: The qubits that the barrier will cover. :returns: A barrier `cirq.Operation` on the provided qubits. .. py:function:: deserialize_circuits(serialized_circuits: str) -> list[cirq.Circuit] Deserialize serialized circuit(s). :param serialized_circuits: A json string generated via `serialization.serialize_circuit()`. :returns: The circuit or list of circuits that was serialized. .. py:function:: measured_qubit_indices(circuit: cirq.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). :param circuit: The input quantum circuit. :returns: A list of the measurement qubit indicies. :raises ValueError: If qubit indices are requested for non-line qubits. .. py:function:: parallel_gates_operation(*ops: cirq.Operation) -> cirq.Operation Constructs a parallel gates operation. Given operations acting on disjoint qubits, constructs a single `cirq_superstaq.ParallelGates` instance and applies it such that each operation's `.gate` is applied to its `.qubits`. :param 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. :raises ValueError: If the operation has tags. .. py:function:: qubit_subspace_op(sub_op: cirq.Operation, qid_shape: collections.abc.Sequence[int], subspaces: collections.abc.Sequence[tuple[int, int]] | None = None) -> cirq.Operation Embeds a qubit Operation into a given subspace of a higher-dimensional Operation. Uses `QubitSubspaceGate`. :param sub_op: The `cirq.Operation` to embed. :param qid_shape: The dimensions of the subspace. :param 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. .. py:function:: qudit_swap_op(qudit0: cirq.Qid, qudit1: cirq.Qid) -> cirq.Operation Construct a SWAP gate and apply it to the provided qudits. If both qudits have dimension 2, uses `cirq.SWAP`; otherwise uses `QuditSwapGate`. :param qudit0: The first qudit to swap. :param 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. .. py:function:: serialize_circuits(circuits: cirq.AbstractCircuit | collections.abc.Sequence[cirq.AbstractCircuit]) -> str Serialize circuit(s) into a json string. :param circuits: A `cirq.Circuit` or list of `cirq.Circuits` to be serialized. :returns: A string representing the serialized circuit(s). .. py:data:: AQTICCX .. py:data:: AQTITOFFOLI .. py:data:: AceCRMinusPlus .. py:data:: AceCRPlusMinus .. py:data:: BSWAP .. py:data:: BSWAP_INV .. py:data:: CR .. py:data:: CZ3 .. py:data:: CZ3_INV .. py:data:: DD .. py:data:: QutritZ0 .. py:data:: QutritZ1 .. py:data:: QutritZ2 .. py:data:: SUPERSTAQ_RESOLVERS .. py:data:: SWAP3 .. py:data:: ZX