qiskit_superstaq.superstaq_provider =================================== .. py:module:: qiskit_superstaq.superstaq_provider Classes ------- .. autoapisummary:: qiskit_superstaq.superstaq_provider.SuperstaqProvider Module Contents --------------- .. py:class:: SuperstaqProvider(api_key: str | None = None, remote_host: 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: Any) Bases: :py:obj:`general_superstaq.service.Service` Provider for Superstaq backend. Typical usage is: .. code-block:: python import qiskit_superstaq as qss ss_provider = qiskit_superstaq.SuperstaqProvider("MY_TOKEN") backend = ss_provider.get_backend("target") where `MY_TOKEN` is the access token provided by Superstaq, and `target` is the name of the desired backend. .. py:method:: aqt_compile(circuits: qiskit.QuantumCircuit | collections.abc.Sequence[qiskit.QuantumCircuit], target: str = 'aqt_keysight_qpu', *, num_eca_circuits: int | None = None, random_seed: int | None = None, atol: float | None = None, gate_defs: collections.abc.Mapping[str, str | numpy.typing.NDArray[numpy.number[Any]] | None] | None = None, gateset: collections.abc.Mapping[str, collections.abc.Sequence[collections.abc.Sequence[int]]] | None = None, pulses: object = None, variables: object = None, **kwargs: Any) -> qiskit_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: A string containing the name of a target AQT backend. :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 either a unitary matrix or None. More specific associations take precedence, for example `{"SWAP": , "SWAP/C5C4": }` implies `` for all "SWAP" calibrations except "SWAP/C5C4" (which will instead be mapped to `` applied to 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: qiskit.QuantumCircuit | collections.abc.Sequence[qiskit.QuantumCircuit], num_equivalent_circuits: int, random_seed: int | None = None, target: str = 'aqt_keysight_qpu', atol: float | None = None, gate_defs: collections.abc.Mapping[str, str | numpy.typing.NDArray[numpy.number[Any]] | None] | None = None, **kwargs: Any) -> qiskit_superstaq.compiler_output.CompilerOutput Compiles and optimizes the given circuit(s) for the Advanced Quantum Testbed (AQT) at Lawrence Berkeley National Laboratory using Equivalent Circuit Averaging (ECA). See arxiv.org/pdf/2111.04572.pdf for a description of ECA. .. note:: This method has been deprecated. Instead, use the `num_eca_circuits` argument of `aqt_compile()`. :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: A string containing the name of a target AQT backend. :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 either a unitary matrix or None. More specific associations take precedence, for example `{"SWAP": , "SWAP/C5C4": }` implies `` for all "SWAP" calibrations except "SWAP/C5C4" (which will instead be mapped to `` applied to 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:: backends(simulator: bool | None = None, supports_submit: bool | None = None, supports_submit_qubo: bool | None = None, supports_compile: bool | None = None, available: bool | None = None, retired: bool | None = None, accessible: bool | None = None, **kwargs: bool) -> list[qiskit_superstaq.SuperstaqBackend] Lists the backends available from this provider. :param simulator: Optional flag to restrict the list of targets to (non-) simulators. :param supports_submit: Optional boolean flag to only return targets that (don't) allow circuit submissions. :param supports_submit_qubo: Optional boolean flag to only return targets that (don't) allow qubo submissions. :param supports_compile: Optional boolean flag to return targets that (don't) support circuit compilation. :param available: Optional boolean flag to only return targets that are (not) available to use. :param retired: Optional boolean flag to only return targets that are or are not retired. :param accessible: Optional boolean flag to only return targets that are (not) accessible to the user. :param kwargs: Any additional, supported flags to restrict/filter returned targets. :returns: A list of Superstaq backends. .. py:method:: cq_compile(circuits: qiskit.QuantumCircuit | collections.abc.Sequence[qiskit.QuantumCircuit], 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) -> qiskit_superstaq.compiler_output.CompilerOutput Compiles the given circuit(s) to CQ device, optimized to its native gate set. :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 is an optimized qiskit circuit(s). :raises ValueError: If `target` is not a valid CQ target. .. py:method:: get_backend(target: str) -> qiskit_superstaq.SuperstaqBackend Returns a Superstaq backend. :param target: A string containing the name of a target backend. :returns: A Superstaq backend. .. py:method:: get_job(job_id: str) -> qiskit_superstaq.SuperstaqJob 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 `qiskit_superstaq.SuperstaqJob` which can be queried for status or results. :raises ~general_superstaq.SuperstaqServerException: If there was an error accessing the API. :raises ~general_superstaq.SuperstaqException: If retrived jobs are from different targets. .. py:method:: ibmq_compile(circuits: qiskit.QuantumCircuit | collections.abc.Sequence[qiskit.QuantumCircuit], target: str, *, dynamical_decoupling: bool = True, dd_strategy: str = 'adaptive', **kwargs: Any) -> qiskit_superstaq.compiler_output.CompilerOutput Returns pulse schedule(s) for the given qiskit circuit(s) and target. 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: A string containing the name of a target IBMQ backend. :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 circuits(s), and whose .pulse_gate_circuit(s) attribute contains the corresponding pulse schedule(s) (when available). :raises ValueError: If `target` is not a valid IBMQ target. .. 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: qiskit.QuantumCircuit | collections.abc.Sequence[qiskit.QuantumCircuit], 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, atol: float = 1e-08, atol_map: _typeshed.SupportsItems[tuple[int, Ellipsis], float] | None = None, **kwargs: Any) -> qiskit_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 `qiskit.QuantumCircuit` 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: A string containing the name of a target backend. :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 present in the compiled circuit(s) and Jaqal program(s) (otherwise this will be determined from the input). :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. :param atol: Optional tolerance (trace distance bound) used for approximate compilation. Superstaq will elide gates which can be approximated within the given tolerance by identity operations. :param atol_map: Optional dictionary assigning compilation tolerances to physical qubits, in the form `{: , ...}` where `` is a tuple of physical qubit indices (ints) and `` is an absolute tolerance (trace distance bound) for gates acting on those qubits (for example `{(0, 1): 0.3, (1, 2): 0.2}`). If provided, these tolerances will override `atol` for gates on the given qubits. Omitted qubit pairs default to `atol`. :param kwargs: Other desired qscout_compile options. :returns: Object whose .circuit(s) attribute contains optimized `qiskit.QuantumCircuit`(s), and `.jaqal_program` attribute contains the corresponding Jaqal program(s). :raises ValueError: If `target` is not a valid QSCOUT target. :raises ValueError: If `base_entangling_gate` is not a valid gate option. .. py:method:: resource_estimate(circuits: qiskit.QuantumCircuit | collections.abc.Sequence[qiskit.QuantumCircuit], target: str) -> general_superstaq.ResourceEstimate | list[general_superstaq.ResourceEstimate] Generates resource estimates for qiskit circuit(s). :param circuits: The circuit(s) used during resource estimation. :param target: A string containing the name of a target backend. :returns: ResourceEstimate(s) containing resource costs (after compilation) for running circuit(s) on a backend. .. py:method:: submit_dfe(rho_1: tuple[qiskit.QuantumCircuit, str], rho_2: tuple[qiskit.QuantumCircuit, str], num_random_bases: int, shots: int, **kwargs: Any) -> list[str] Executes the circuits necessary for the DFE protocol. The circuits used to prepare the desired states should not contain final measurements, but can contain mid-circuit measurements (as long as the intended target supports them). For example, to prepare a Bell state to be ran in `ss_unconstrained_simulator`, you should pass `qc = qiskit.QuantumCircuit(2); qc.h(0); qc.cx(0, 1)` as the first element of some `rho_i` (note there are no final measurements). The fidelity between states is calculated following the random measurement protocol outlined in [1]. .. 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 `qiskit.QuantumCircuit` 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 `qiskit.QuantumCircuit` 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 `qiskit.QuantumCircuit`. :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[qiskit.QuantumCircuit], numpy.typing.NDArray[numpy.float64]] Returns Supercheq randomly generated circuits and the corresponding fidelity matrices. .. rubric:: References [1] P. Gokhale et al., *SupercheQ: Quantum Advantage for Distributed Databases*, (2022). https://arxiv.org/abs/2212.03850. :param files: A list of files specified as binary using ints. For example: [[1, 0, 1], [1, 1, 1]]. :param num_qubits: The number of qubits to run Supercheq on. :param depth: The depth of the circuits to run Supercheq on. :returns: A tuple containing a list of qiskit.QuantumCircuits and a list of corresponding fidelity matrices.