general_superstaq

Submodules

• general_superstaq.check
• general_superstaq.resource_estimate
• general_superstaq.serialization
• general_superstaq.service
• general_superstaq.superstaq_client
• general_superstaq.superstaq_exceptions
• general_superstaq.testing
• general_superstaq.typing
• general_superstaq.validation

Attributes

API_URL
API_VERSION

Exceptions

SuperstaqException	An exception for errors coming from Superstaq's API.
SuperstaqServerException	An exception for non-retriable server-side errors.
SuperstaqUnsuccessfulJobException	An exception for attempting to get info about an unsuccessful job.
SuperstaqWarning	A warning issued by the server.

Classes

ResourceEstimate	A class to store data returned from a /resource_estimate request.
Service	This class contains all the services that are used to operate Superstaq.
Target	A data class to store data returned from a /get_targets request.

Package Contents

exception general_superstaq.SuperstaqException(message: str)

Bases: Exception

An exception for errors coming from Superstaq’s API.

message

exception general_superstaq.SuperstaqServerException(message: str, status_code: int = 400, contact_info: bool = False)

Bases: SuperstaqException

An exception for non-retriable server-side errors.

status_code = 400

exception general_superstaq.SuperstaqUnsuccessfulJobException(job_id: str, status: str)

Bases: SuperstaqException

An exception for attempting to get info about an unsuccessful job.

This exception occurs when a job has been cancelled, deleted, or failed, and information about this job is attempted to be accessed.

exception general_superstaq.SuperstaqWarning(message: str)

Bases: Warning

A warning issued by the server.

class general_superstaq.ResourceEstimate

A class to store data returned from a /resource_estimate request.

depth: int | None = None

json_data: dataclasses.InitVar[dict[str, int]] = None

num_single_qubit_gates: int | None = None

num_two_qubit_gates: int | None = None

class general_superstaq.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)

This class contains all the services that are used to operate Superstaq.

add_new_user(name: str, email: str) → str

Adds new user.

Parameters:

• name – The name to add.

• email – The new user’s email.

Returns:

String containing status of update (whether or not it failed) and the new user’s token.

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.

Parameters:

• pulses_file_path – Where to write the pulse configuration.

• variables_file_path – Where to write the variable configuration.

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

• ModuleNotFoundError – If file paths are unspecified and PyYAML cannot be imported.

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”).

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.

Parameters:

• pulses – PulseManager or file path for pulse configuration.

• variables – VariableManager or file path for variable configuration.

Returns:

A status of the update (whether or not it failed).

get_balance(pretty_output: bool = True) → str | float

Get the querying user’s account balance in USD.

Parameters:

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.

get_my_targets() → list[general_superstaq.Target]

Gets a list of Superstaq targets that the user can submit to and are available along with their status information.

Returns:

A list of Superstaq targets that the user can currently submit to.

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.

Parameters:

• simulator – Optional flag to restrict the list of targets to (non-) simulators.

• supports_submit – Optional boolean flag to only return targets that (don’t) allow circuit submissions.

• supports_submit_qubo – Optional boolean flag to only return targets that (don’t) allow qubo submissions.

• supports_compile – Optional boolean flag to return targets that (don’t) support circuit compilation.

• available – Optional boolean flag to only return targets that are (not) available to use.

• retired – Optional boolean flag to only return targets that are or are not retired.

• accessible – Optional boolean flag to only return targets that are (not) accessible to the user.

• kwargs – Any additional, supported flags to restrict/filter returned targets.

Returns:

A list of Superstaq targets matching all provided criteria.

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 name and/or email keyword only arguments which can be used to search for the info of arbitrary users on the server.

Parameters:

• name – A name to search by. Defaults to None.

• email – An email address to search by. Defaults to None.

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

process_aces(job_id: str) → list[float]

Process a job submitted through submit_aces.

Parameters:

job_id – The job id returned by submit_aces.

Returns:

The estimated eigenvalues.

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.

Parameters:

• target – The device target to characterize.

• qubits – A list with the qubit indices to characterize.

• shots – How many shots to use per circuit submitted.

• num_circuits – How many random circuits to use in the protocol.

• mirror_depth – The half-depth of the mirror portion of the random circuits.

• extra_depth – The depth of the fully random portion of the random circuits.

• method – Which type of method to execute the circuits with.

• noise – Noise model to simulate the protocol with. Valid strings are “symmetric_depolarize”, “phase_flip”, “bit_flip” and “asymmetric_depolarize”.

• error_prob – The error probabilities if a string was passed to noise. * For “asymmetric_depolarize”, error_prob will be a three-tuple with the error rates for the X, Y, Z gates in that order. So, a valid argument would be error_prob = (0.1, 0.1, 0.1). Notice that these values must add up to less than or equal to 1. * For the other channels, error_prob is one number less than or equal to 1, e.g., error_prob = 0.1.

• tag – Tag for all jobs submitted for this protocol.

• lifespan – How long to store the jobs submitted for in days (only works with right permissions).

Returns:

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

Raises:

• ValueError – If the target or noise model are not valid.

• SuperstaqServerException – If the request fails.

submit_qubo(qubo: collections.abc.Mapping[tuple[TQuboKey, Ellipsis], float], target: str = 'ss_unconstrained_simulator', repetitions: int = 10, method: str | None = None, max_solutions: int = 1000) → list[dict[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.

Parameters:

• 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}.

• target – The target to submit the QUBO.

• repetitions – Number of times that the execution is repeated before stopping.

• method – The parameter specifying method of QUBO solving execution. Currently, will either be the “dry-run” option which runs on dwave’s simulated annealer, or defaults to None and sends it directly to the specified target.

• max_solutions – A parameter that specifies the max number of output solutions.

Returns:

A dictionary containing the output solutions.

update_user_balance(email: str, balance: float) → str

Updates user’s balance.

Parameters:

• email – The new user’s email.

• balance – The new balance.

Raises:

superstaq.SuperstaqException – If requested balance exceeds the limit.

Returns:

String containing status of update (whether or not it failed).

update_user_role(email: str, role: int) → str

Updates user’s role.

Parameters:

• email – The new user’s email.

• role – The new role.

Returns:

String containing status of update (whether or not it failed).

class general_superstaq.Target(/, **data: Any)

Bases: pydantic.BaseModel

A data class to store data returned from a /get_targets request.

accessible: bool = False

available: bool = False

retired: bool = False

supports_compile: bool = False

supports_submit: bool = False

supports_submit_qubo: bool = False

target: str

general_superstaq.API_URL = 'https://superstaq.infleqtion.com'

general_superstaq.API_VERSION = 'v0.2.0'