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, 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 – 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: Any, variables: Any) str

Uploads configs for AQT.

Arguments can be either file paths (in .yaml format) or qtrl Manager instances.

Parameters:
  • pulsesPulseManager or file path for pulse configuration.

  • variablesVariableManager 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_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[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.

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

Returns:

A list of Superstaq targets matching all provided criteria.

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:
submit_qubo(qubo: QUBO, target: str, repetitions: int = 1000, method: str | None = None, max_solutions: int = 1000) Dict[str, str]

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

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
class general_superstaq.typing.Target(*, target: str, supports_submit: bool = False, supports_submit_qubo: bool = False, supports_compile: bool = False, available: bool = False, retired: bool = False)

Bases: BaseModel

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

available: bool
retired: bool
supports_compile: bool
supports_submit: bool
supports_submit_qubo: bool
target: str

general_superstaq.validation module

general_superstaq.validation.validate_integer_param(integer_param: object, min_val: int = 1) None

Validates that integer_param is an integer and positive (or above a minimum value).

Parameters:
  • integer_param – The input parameter to validate.

  • min_val – Optional parameter to validate if integer_param is greater than min_val.

Raises:
  • TypeError – If integer_param is not an integer.

  • ValueError – If integer_param is less than min_val.

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.

Parameters:

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.

class general_superstaq.Target(*, target: str, supports_submit: bool = False, supports_submit_qubo: bool = False, supports_compile: bool = False, available: bool = False, retired: bool = False)

Bases: BaseModel

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

available: bool
retired: bool
supports_compile: bool
supports_submit: bool
supports_submit_qubo: bool
target: str