general_superstaq

Submodules

• general_superstaq.check
• general_superstaq.compiler_output
• general_superstaq.job
• general_superstaq.machine_api
• general_superstaq.models
• 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_URL_V3
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

BaseCompilerOutput	A base class that stores the results of compiled circuits.
JaqalService	This class contains services relating to Superstaq and Jaqal input.
Job	A job created on the Superstaq API.
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.BaseCompilerOutput(circuits: C | list[C] | list[list[C]], initial_logical_to_physicals: dict[Q, Q] | list[dict[Q, Q]] | list[list[dict[Q, Q]]], final_logical_to_physicals: dict[Q, Q] | list[dict[Q, Q]] | list[list[dict[Q, Q]]], pulse_gate_circuits: Any | None = None, seq: Any | None = None, jaqal_programs: list[str] | None = None)

Bases: Generic[C, Q]

A base class that stores the results of compiled circuits.

has_multiple_circuits() → bool

Checks if this object has plural attributes (e.g. .circuits).

Otherwise, the object represents a single circuit, and has singular attributes (.circuit).

Returns:

A boolean indicating whether this object represents multiple circuits.

property jaqal_program: str | None

Jaqal program(s) as a single string.

For multi-circuit compilation the string will contain subcircuits.

jaqal_programs = None

seq = None

class general_superstaq.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: BaseService

This class contains services relating to Superstaq and Jaqal input.

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.

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

Parameters:

• jaqal_programs – The Jaqal program string(s) to compile.

• target – String of target representing target device.

• num_eca_circuits – Optional number of logically equivalent random Jaqal programs to generate from each input Jaqal program for Equivalent Circuit Averaging (ECA).

• mirror_swaps – Whether to use mirror swapping to reduce two-qubit gate overhead.

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

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

• error_rates – Optional dictionary assigning relative error rates to pairs of physical qubits, in the form {<qubit_indices>: <error_rate>, …} where <qubit_indices> is a tuple physical qubit indices (ints) and <error_rate> 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.

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

• atol_map – Optional dictionary assigning compilation tolerances to physical qubits, in the form {<qubit_indices>: <atol>, …} where <qubit_indices> is a tuple of physical qubit indices (ints) and <atol> 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.

• keep_qubit_order – If True, do not reorder input qubits when compiling with ECA.

• random_seed – Used to seed any stochastic compilation passes (especially for ECA).

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

• ValueError – If target is not a valid QSCOUT target.

• ValueError – If provided num_qubits is less than the register size required by jaqal_programs.

class general_superstaq.Job(client: general_superstaq.superstaq_client._SuperstaqClientV3, job_id: uuid.UUID | str)

A job created on the Superstaq API.

Note that this is mutable, when calls to get status or results are made the job updates itself If a job is canceled or deleted, only the job id and the status remain valid.

cancel(**kwargs: object) → None

Cancel the current job if it is not in a terminal state.

Parameters:

• index – An optional index of the specific sub-job to cancel.

• kwargs – Extra options needed to fetch jobs.

Raises:

• SuperstaqServerException – If unable to get the status of the job from the API or

• cancellations were unsuccessful. –

job_id() → uuid.UUID

Gets the job id of this job.

This is the unique identifier used for identifying the job by the API.

Returns:

This job’s id (a string).

set_counts(results: collections.abc.Sequence[collections.abc.Mapping[str, float]] | jaqalpaq.run.result.ExecutionResult | jaqalpaq.run.result.SubbatchView) → None

Manually input experimental counts for all circuits in this job.

Also accepts JaqalPaq ExecutionResult or SubbatchView objects. Both are assumed to have as many subcircuits as this job contains compiled circuits. For ExecutionResult objects containing multiple sub-batches, only the first is used. (requires jaqalpaq>=1.3.0)

Parameters:

results – A sequence of experimental counts dictionaries to load, each of which should be formatted as required by Job.set_counts_for_circuit. Can also be one of the JaqalPaq results objects described above. In either case, assumed to contain counts for every compiled circuit contained in this job.

set_counts_for_circuit(index: int, result: collections.abc.Mapping[str, int] | jaqalpaq.run.result.SubcircuitView) → None

Manually input experimental counts for one circuits in this job.

Also accepts JaqalPaq SubcircuitView, e.g. from result.by_subbatch[i].by_subcircuit[j] where result is a JaqalPaq ExecutionResult object. (requires jaqalpaq>=1.3.0)

Parameters:

• index – The circuit index for which to update counts.

• result – An experimental counts dictionary to load (or a JaqalPaq SubcircuitView). Counts dictionaries must be formatted with bitstrings as keys and total counts (or probabilities) as values, e.g. {“000”: 100, “111”: 200}.

target() → str

Gets the Superstaq target associated with this job.

Returns:

The target to which this job was submitted.

Raises:

SuperstaqServerException – If unable to get the job from the API.

to_dict() → dict[str, general_superstaq.typing.Job]

Refreshes and returns job information.

Note

The contents of this dictionary are not guaranteed to be consistent over time. Whenever possible, users should use the specific Job methods to retrieve the desired job information instead of relying on particular entries in the output of this method.

Returns:

A dictionary containing updated job information.

wait_until_complete(index: int | None = None, timeout_seconds: float | None = None, polling_seconds: float = 5) → None

Waits until either the job is done or some error in the job occurs.

Parameters:

• index – An optional index of the specific circuit to wait for (otherwise waits for all circuits to complete).

• timeout_seconds – The total number of seconds to poll for.

• polling_seconds – The interval with which to poll.

STATUS_PRIORITY_ORDER

endianness

property job_data: general_superstaq.models.JobData

property metadata: dict[str, object]

Any metadata passed when creating this job.

property tags: list[str]

All tags associated with this job.

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] = 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)

Bases: BaseService

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

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

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_atom_picture(bitmap: numpy.typing.ArrayLike) → str

Performs a POST request on the /atom_picture endpoint.

Parameters:

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.

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.

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, the supported methods include “bruteforce”, “sim_anneal”, “qaoa”, or “rqaoa”. Defaults to “sim_anneal” which runs on DWave’s simulated annealer.

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

• qaoa_depth – The number of QAOA layers to use. Defaults to 1.

• rqaoa_cutoff – The stopping point for RQAOA before using switching to a classical solver. Defaults to 0.

• dry_run – If method=”qaoa”, a boolean flag to (not) run an ideal ‘dry-run’ QAOA execution on target.

• random_seed – Optional random seed choice for RQAOA.

• kwargs – Any optional keyword arguments supported by the qubo solver methods.

Returns:

A dictionary containing the output solutions.

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_URL_V3 = 'https://superstaq-prod.infleqtion.com'

general_superstaq.API_VERSION = 'v0.2.0'