general_superstaq package

Subpackages

Submodules

general_superstaq.qubo module

general_superstaq.qubo.read_json_qubo_result(json_dict: Dict[str, str]) → List[Dict[Tuple[int], int]]

Reads out returned JSON from Superstaq API’s QUBO endpoint.

Parameters:: json_dict – A JSON dictionary matching the format returned by the /qubo endpoint.
Returns:: A numpy.recarray containing the results of the optimization.

general_superstaq.resource_estimate module

class general_superstaq.resource_estimate.ResourceEstimate(num_single_qubit_gates: int | None = None, num_two_qubit_gates: int | None = None, depth: int | None = None, json_data: dataclasses.InitVar[Dict[str, int]] = None)

Bases: object

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

general_superstaq.serialization module

general_superstaq.serialization.bytes_to_str(bytes_data: bytes) → str

Convert arbitrary bytes data into a string.

Parameters:: bytes_data – The data to be converted.
Returns:: The string from conversion.

general_superstaq.serialization.deserialize(serialized_obj: str) → Any

Deserialize serialized objects.

Parameters:: serialized_obj – A string generated via general_superstaq.serialization.serialize.
Returns:: The serialized object.

general_superstaq.serialization.serialize(obj: Any) → str

Serialize picklable object into a string.

Parameters:: obj – A picklable object to be serialized.
Returns:: The string representing the serialized object.

general_superstaq.serialization.str_to_bytes(str_data: str) → bytes

Decode the string-encoded bytes data returned by bytes_to_str.

Parameters:: str_data – The string data to be decoded.
Returns:: The decoded by bytes data.

general_superstaq.service module

class general_superstaq.service.Service(api_key: str | None = None, remote_host: str | None = None, default_target: str | None = None, api_version: str = 'v0.2.0', max_retry_seconds: int = 3600, verbose: bool = False)

Bases: object

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 (optional) – Where to write the pulse configuration.
variables_file_path (optional) – 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: Any, variables: Any) → 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.

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: 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 is not valid.
SuperstaqServerException – If the request fails.

submit_qubo(qubo: QUBO, target: str, repetitions: int = 1000, method: str | None = None, max_solutions: int = 1000) → Dict[str, str]

Solves the QUBO given via the submit_qubo function in superstaq_client, and 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 qv.QUBO object.
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,
annealer (will either be the "dry-run" option which runs on dwave's simulated) –

:param : :param or defauls to none and sends it directly to the specified target.: :param max_solutions: A parameter that specifies the max number of output solutions.

Returns:: A dictionary returned by the submit_qubo function.

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

Updates user’s balance.

Parameters:

email – The new user’s email.
balance – The new balance.

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

general_superstaq.superstaq_client module

Client for making requests to Superstaq’s API.

general_superstaq.superstaq_client.find_api_key() → str

Function to try to load a Superstaq API key from the environment or a key file.

Raises:

OSError – If the Superstaq API key could not be found in the environment.
EnvironmentError – If the Superstaq API key could not be found.

Returns:

Superstaq API key string.

general_superstaq.superstaq_exceptions module

Exceptions for the Superstaq API.

exception general_superstaq.superstaq_exceptions.SuperstaqException(message: str)

Bases: Exception

An exception for errors coming from Superstaq’s API.

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

Bases: SuperstaqException

An exception for non-retriable server-side errors.

exception general_superstaq.superstaq_exceptions.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.superstaq_exceptions.SuperstaqWarning(message: str)

Bases: Warning

A warning issued by the server.

general_superstaq.typing module

class general_superstaq.typing.Job(*args, **kwargs)

Bases: dict

circuit_type: str

compiled_circuit: str

data: Dict[str, Any] | None

input_circuit: str | None

num_qubits: int

provider_id: str

samples: Dict[str, int] | None

shots: int | None

state_vector: str | None

status: str

target: str

general_superstaq.validation module

general_superstaq.validation.validate_integer_param(integer_param: object) → None

Validates that an input parameter is positive and an integer.

Parameters:

integer_param – An input parameter.

Raises:

TypeError – If input is not an integer.
ValueError – If input is negative.

general_superstaq.validation.validate_noise_type(noise: Dict[str, object], n_qubits: int) → None

Validates that an ACES noise model is valid.

Parameters:

noise – A noise model parameter.
n_qubits – Number of qubits the noise model is applied to.

Raises:

ValueError – If noise is not valid.

general_superstaq.validation.validate_target(target: str) → None

Checks that a target contains a valid format, vendor prefix, and device type. :param target: A string containing the name of a target device.

Raises:: ValueError – If target has an invalid format, vendor prefix, or device type.

Module contents

class general_superstaq.ResourceEstimate(num_single_qubit_gates: int | None = None, num_two_qubit_gates: int | None = None, depth: int | None = None, json_data: dataclasses.InitVar[Dict[str, int]] = None)

Bases: object

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

exception general_superstaq.SuperstaqException(message: str)

Bases: Exception

An exception for errors coming from Superstaq’s API.

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

Bases: SuperstaqException

An exception for non-retriable server-side errors.

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.