cirq_superstaq.job ================== .. py:module:: cirq_superstaq.job .. autoapi-nested-parse:: Represents a job created via the Superstaq API. Classes ------- .. autoapisummary:: cirq_superstaq.job.Job cirq_superstaq.job.JobV3 Module Contents --------------- .. py:class:: Job(client: general_superstaq.superstaq_client._SuperstaqClient, 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. .. py:method:: cancel(index: int | None = None, **kwargs: object) -> None Cancel the current job if it is not in a terminal state. :param index: An optional index of the specific sub-job to cancel. :param kwargs: Extra options needed to fetch jobs. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API or cancellations were unsuccessful. .. py:method:: compiled_circuits(index: int) -> cirq.Circuit compiled_circuits(index: None = None) -> list[cirq.Circuit] Gets the compiled circuits that were processed for this job. :param index: An optional index of the specific circuit to retrieve. :returns: A single compiled circuit or list of compiled circuits. .. py:method:: 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). :param index: The index of the circuit which the counts correspond to. :param timeout_seconds: The total number of seconds to poll for. :param polling_seconds: The interval with which to poll. :param 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 ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the results from the API. :raises TimeoutError: If no results are available in the provided timeout interval. .. py:method:: input_circuits(index: int) -> cirq.Circuit input_circuits(index: None = None) -> list[cirq.Circuit] Gets the original circuits that were submitted for this job. :param index: An optional index of the specific circuit to retrieve. :returns: A single input circuit or list of submitted input circuits. .. py:method:: 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). .. py:method:: num_qubits(index: int) -> int num_qubits(index: None = None) -> list[int] Gets the number of qubits required for each circuit in this job. :param 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 ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API. .. py:method:: pulse_gate_circuits(index: int | None = None) -> Any Gets the pulse gate circuit(s) returned by this job. :param 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. :raises ValueError: If the job's target does not use pulse gate circuits. .. py:method:: repetitions() -> int Gets the number of repetitions requested for this job. :returns: The number of repetitions for this job. :raises ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API. .. py:method:: 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`. :param index: An optional index of the specific sub-job to get the status of. :raises ~general_superstaq.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`. .. py:method:: target() -> str Gets the Superstaq target associated with this job. :returns: The target to which this job was submitted. :raises ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API. .. py:method:: 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. .. py:attribute:: ALL_STATES :value: ('Done', 'Canceled', 'Failed', 'Deleted', 'Ready', 'Submitted', 'Running', 'Queued') .. py:attribute:: NON_TERMINAL_STATES :value: ('Ready', 'Submitted', 'Running', 'Queued') .. py:attribute:: TERMINAL_STATES :value: ('Done', 'Canceled', 'Failed', 'Deleted') .. py:attribute:: UNSUCCESSFUL_STATES :value: ('Canceled', 'Failed', 'Deleted') .. py:class:: JobV3(client: general_superstaq.superstaq_client._SuperstaqClientV3, job_id: uuid.UUID | str) ***NEW API STANDARD*** 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. .. py:method:: cancel(**kwargs: object) -> None Cancel the current job if it is not in a terminal state. :param index: An optional index of the specific sub-job to cancel. :param kwargs: Extra options needed to fetch jobs. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API or cancellations were unsuccessful. .. py:method:: compiled_circuits(index: int) -> cirq.Circuit compiled_circuits(index: None = None) -> list[cirq.Circuit] Gets the compiled circuits that were processed for this job. :param index: An optional index of the specific circuit to retrieve. :raises general_superstaq.SuperstaqException: If the circuit at the provided index has no compiled circuit or, :raises when index is None, if any of the circuits in the job are missing the compiled circuit.: :returns: A single compiled circuit or list of compiled circuits. .. py:method:: 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). :param index: The index of the circuit which the counts correspond to. :param timeout_seconds: The total number of seconds to poll for. :param polling_seconds: The interval with which to poll. :param 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 ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the results from the API. :raises TimeoutError: If no results are available in the provided timeout interval. :raises general_superstaq.SuperstaqException: If the job counts are missing. .. py:method:: input_circuits(index: int) -> cirq.Circuit input_circuits(index: None = None) -> list[cirq.Circuit] Gets the original circuits that were submitted for this job. :param index: An optional index of the specific circuit to retrieve. :returns: A single input circuit or list of submitted input circuits. .. py:method:: 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). .. py:method:: num_qubits(index: int) -> int num_qubits(index: None = None) -> list[int] Gets the number of qubits required for each circuit in this job. :param 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 ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API. .. py:method:: repetitions() -> int Gets the number of repetitions requested for this job. :returns: The number of repetitions for this job. .. py:method:: status(index: int | None = None) -> general_superstaq.models.CircuitStatus 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`. :param index: An optional index of the specific sub-job to get the status of. :raises ~general_superstaq.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`. .. py:method:: target() -> str Gets the Superstaq target associated with this job. :returns: The target to which this job was submitted. :raises ~general_superstaq.SuperstaqUnsuccessfulJobException: If the job failed or has been canceled or deleted. :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API. .. py:method:: 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. .. py:attribute:: STATUS_PRIORITY_ORDER .. py:property:: job_data :type: general_superstaq.models.JobData .. py:property:: metadata :type: dict[str, object] Any metadata passed when creating this job. .. py:property:: tags :type: list[str] All tags associated with this job.