general_superstaq.service ========================= .. py:module:: general_superstaq.service Attributes ---------- .. autoapisummary:: general_superstaq.service.CLIENT_VERSION Classes ------- .. autoapisummary:: general_superstaq.service.BaseService general_superstaq.service.JaqalService general_superstaq.service.Service Module Contents --------------- .. py:class:: BaseService(api_key: str | None = None, remote_host: str | None = None, api_version: str = gss.API_VERSION, max_retry_seconds: int = 3600, verbose: bool = False) This class contains all the basic services that are used to operate Superstaq. .. py:method:: add_new_user(name: str, email: str) -> str Adds new user. :param name: The name to add. :param email: The new user's email. :returns: String containing status of update (whether or not it failed) and the new user's token. .. py:method:: get_balance(pretty_output: bool = True) -> str | float Get the querying user's account balance in USD. :param pretty_output: Whether to return a pretty string or a float of the balance. :returns: If `pretty_output` is `True`, returns the balance as a nicely formatted string ($-prefix, commas on LHS every three digits, and two digits after period). Otherwise, simply returns a float of the balance. .. py:method:: get_my_targets(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, **kwargs: bool) -> list[general_superstaq.Target] Gets a list of Superstaq targets that the user can submit to and are available along with their status information. :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 kwargs: Any additional, supported flags to restrict/filter returned targets. :returns: A list of Superstaq targets that the user can currently submit to. .. py:method:: get_targets(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[general_superstaq.Target] Gets a list of Superstaq targets along with their status information. :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 targets matching all provided criteria. .. py:method:: get_user_info() -> dict[str, str | float] get_user_info(*, name: str) -> list[dict[str, str | float]] get_user_info(*, email: str) -> list[dict[str, str | float]] get_user_info(*, user_id: int) -> list[dict[str, str | float]] get_user_info(*, name: str, user_id: int) -> list[dict[str, str | float]] get_user_info(*, email: str, user_id: int) -> list[dict[str, str | float]] get_user_info(*, name: str, email: str) -> list[dict[str, str | float]] get_user_info(*, name: str, email: str, user_id: int) -> list[dict[str, str | float]] Gets a dictionary of the user's info. .. note:: SUPERTECH users can submit optional :code:`name` and/or :code:`email` keyword only arguments which can be used to search for the info of arbitrary users on the server. :param name: A name to search by. Defaults to None. :param email: An email address to search by. Defaults to None. :param user_id: A user ID to search by. Defaults to None. :returns: A dictionary of the user information. In the case that either the name or email query kwarg is used, a list of dictionaries is returned, corresponding to the user information for each user that matches the query. .. py:method:: update_user_balance(email: str, balance: float) -> str Updates user's balance. :param email: The new user's email. :param balance: The new balance. :raises superstaq.SuperstaqException: If requested balance exceeds the limit. :returns: String containing status of update (whether or not it failed). .. py:method:: update_user_role(email: str, role: int) -> str Updates user's role. :param email: The new user's email. :param role: The new role. :returns: String containing status of update (whether or not it failed). .. py:class:: JaqalService(api_key: str | None = None, remote_host: str | None = None, api_version: str = gss.API_VERSION, max_retry_seconds: int = 3600, verbose: bool = False) Bases: :py:obj:`BaseService` This class contains services relating to Superstaq and Jaqal input. .. py:method:: qscout_compile(jaqal_programs: str | collections.abc.Sequence[str], target: str = 'qscout_peregrine_qpu', *, num_eca_circuits: int | None = None, 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, keep_qubit_order: bool = False, random_seed: int | None = None, **kwargs: Any) -> general_superstaq.compiler_output.CompilerOutput Compiles and optimizes the given Jaqal [1] program(s) for a QSCOUT `target`. Specifying a nonzero value for `num_eca_circuits` enables compilation with Equivalent Circuit Averaging (ECA). See [2] for a description of ECA. .. rubric:: References [1] 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. [2] A. Hashim, et al., Optimized fermionic SWAP networks with equivalent circuit averaging for QAOA. Phys. Rev. Research 4, 033028 (2022). https://arxiv.org/abs/2111.04572 :param jaqal_programs: The Jaqal program string(s) to compile. :param target: String of target representing target device. :param num_eca_circuits: Optional number of logically equivalent random Jaqal programs to generate from each input Jaqal program for Equivalent Circuit Averaging (ECA). :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. Defaults to "xx". :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 `jaqal_programs`). :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 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 keep_qubit_order: If `True`, do not reorder input qubits when compiling with ECA. :param random_seed: Used to seed any stochastic compilation passes (especially for ECA). :param kwargs: Other desired `/qscout_compile` options. :returns: Object whose .circuit(s) attribute contains optimized 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. :raises ValueError: If provided `num_qubits` is less than the register size required by `jaqal_programs`. .. py:class:: Service(api_key: str | None = None, remote_host: str | None = None, api_version: str = gss.API_VERSION, max_retry_seconds: int = 3600, verbose: bool = False) Bases: :py:obj:`BaseService` This class contains all the services that are used to operate Superstaq. .. py:method:: aqt_download_configs(pulses_file_path: str | None = None, variables_file_path: str | None = None, overwrite: bool = False) -> tuple[dict[str, Any], dict[str, Any]] | None Downloads AQT configs that had previously been uploaded to Superstaq. Optionally saves configs to disk as YAML configuration files. Otherwise, the PyYAML package is required to read the downloaded configs. :param pulses_file_path: Where to write the pulse configuration. :param variables_file_path: Where to write the variable configuration. :param overwrite: Whether or not to overwrite existing files. :returns: (If file paths are not provided) a tuple of pulses (a dictionary containing pulse configuration data) and variables (a dictionary containing calibration variables). :raises ValueError: If either file path already exists and overwrite is not True. :raises ModuleNotFoundError: If file paths are unspecified and PyYAML cannot be imported. .. py:method:: aqt_get_configs() -> dict[str, str] Retrieves the raw AQT config files that had previously been uploaded to Superstaq. :returns: A dictionary containing all of the user's configs (as YAML strings), indexed by the config names (e.g. "pulses", "variables"). .. py:method:: aqt_upload_configs(pulses: object, variables: object) -> str Uploads configs for AQT. Arguments can be either file paths (in .yaml format) or qtrl Manager instances. :param pulses: `PulseManager` or file path for pulse configuration. :param variables: `VariableManager` or file path for variable configuration. :returns: A status of the update (whether or not it failed). .. py:method:: process_aces(job_id: str) -> list[float] Process a job submitted through `submit_aces`. :param job_id: The job id returned by `submit_aces`. :returns: The estimated eigenvalues. .. 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 | 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. :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. 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). :returns: A string with the job id for the ACES job created. :raises ValueError: If the target or noise model are not valid. :raises ~general_superstaq.SuperstaqServerException: If the request fails. .. py:method:: submit_atom_picture(bitmap: numpy.typing.ArrayLike) -> str Performs a POST request on the `/atom_picture` endpoint. :param bitmap: A 2D array-like object of integers from the set {0, 1, 2}. '0' is empty, '1' is atom, and '2' is whatever is there. :returns: A string containing the post request id. .. py:method:: submit_qubo(qubo: collections.abc.Mapping[tuple[general_superstaq.typing.TQuboKey, Ellipsis], float], target: str = 'ss_unconstrained_simulator', repetitions: int = 10, method: str = 'sim_anneal', max_solutions: int = 1000, *, qaoa_depth: int = 1, rqaoa_cutoff: int = 0, dry_run: bool = False, random_seed: int | None = None, **kwargs: object) -> list[dict[general_superstaq.typing.TQuboKey, int]] Solves a submitted QUBO problem via annealing. This method returns any number of specified dictionaries that seek the minimum of the energy landscape from the given objective function known as output solutions. :param qubo: A dictionary representing the QUBO object. The tuple keys represent the boolean variables of the QUBO and the values represent the coefficients. As an example, for a QUBO with integer coefficients = 2*a + a*b - 5*b*c - 3 (where a, b, and c are boolean variables), the corresponding dictionary format would be {('a',): 2, ('a', 'b'): 1, ('b', 'c'): -5, (): -3}. :param target: The target to submit the QUBO. :param repetitions: Number of times that the execution is repeated before stopping. :param method: The parameter specifying method of QUBO solving execution. Currently, the supported methods include "bruteforce", "sim_anneal", "qaoa", or "rqaoa". Defaults to "sim_anneal" which runs on DWave's simulated annealer. :param max_solutions: A parameter that specifies the max number of output solutions. :param qaoa_depth: The number of QAOA layers to use. Defaults to 1. :param rqaoa_cutoff: The stopping point for RQAOA before using switching to a classical solver. Defaults to 0. :param dry_run: If `method="qaoa"`, a boolean flag to (not) run an ideal 'dry-run' QAOA execution on `target`. :param random_seed: Optional random seed choice for RQAOA. :param kwargs: Any optional keyword arguments supported by the qubo solver methods. :returns: A dictionary containing the output solutions. .. py:data:: CLIENT_VERSION