cirq_superstaq.job

Represents a job created via the Superstaq API.

Classes

Job

A job created on the Superstaq API.

Module Contents

class cirq_superstaq.job.Job(client: general_superstaq.superstaq_client._BaseSuperstaqClient, job_id: 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 to the results returned from the API.

If a job is canceled or deleted, only the job id and the status remain valid.

cancel(index: int | None = None, **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.

compiled_circuits(index: int) → cirq.Circuit
compiled_circuits(index: None = None) → list[cirq.Circuit]

Gets the compiled circuits that were processed for this job.

Parameters:

index – An optional index of the specific circuit to retrieve.

Returns:

A single compiled circuit or list of compiled circuits.

counts(index: int, timeout_seconds: int = 7200, polling_seconds: float = 1.0, qubit_indices: collections.abc.Sequence[int] | None = None) → dict[str, int]
counts(index: None = None, timeout_seconds: int = 7200, polling_seconds: float = 1.0, qubit_indices: collections.abc.Sequence[int] | None = None) → list[dict[str, int]]

Polls the Superstaq API for counts results (frequency of each measurement outcome).

Parameters:

  • index – The index of the circuit which the counts correspond to.

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

  • polling_seconds – The interval with which to poll.

  • qubit_indices – If provided, only include measurements counts of these qubits.

Returns:

A dictionary containing the frequency counts of the measurements the job indexed by index or a list of such dictionaries for each respective sub-job.

Raises:
input_circuits(index: int) → cirq.Circuit
input_circuits(index: None = None) → list[cirq.Circuit]

Gets the original circuits that were submitted for this job.

Parameters:

index – An optional index of the specific circuit to retrieve.

Returns:

A single input circuit or list of submitted input circuits.

job_id() → str

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

num_qubits(index: int) → int
num_qubits(index: None = None) → list[int]

Gets the number of qubits required for each circuit in this job.

Parameters:

index – The index of the circuit to get number of qubits from.

Returns:

A list of the numbers of qubits in all circuits or just a single qubit number for the given circuit index.

Raises:
pulse_gate_circuits(index: int | None = None) → Any

Gets the pulse gate circuit(s) returned by this job.

Parameters:

index – An optional index of the pulse gate circuit to retrieve.

Returns:

A qiskit.QuantumCircuit pulse gate circuit or list of qiskit.QuantumCircuit pulse gate circuits.

Raises:

  • ValueError – If the job was not run on an IBM pulse device.

  • ValueError – If the job’s target does not use pulse gate circuits.

repetitions() → int

Gets the number of repetitions requested for this job.

Returns:

The number of repetitions for this job.

Raises:
status(index: int | None = None) → str

Gets the current status of the job.

If the current job is in a non-terminal state, this will update the job and return the current status. A full list of states is given in cirq_superstaq.Job.ALL_STATES.

Parameters:

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

Raises:

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

Returns:

The status of the job indexed by index or the overall job status if index is None.

target() → str

Gets the Superstaq target associated with this job.

Returns:

The target to which this job was submitted.

Raises:
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.

ALL_STATES = ('Done', 'Canceled', 'Failed', 'Deleted', 'Ready', 'Submitted', 'Running', 'Queued')
NON_TERMINAL_STATES = ('Ready', 'Submitted', 'Running', 'Queued')
TERMINAL_STATES = ('Done', 'Canceled', 'Failed', 'Deleted')
UNSUCCESSFUL_STATES = ('Canceled', 'Failed', 'Deleted')