general_superstaq.job
=====================

.. py:module:: general_superstaq.job

.. autoapi-nested-parse::

   Represents a job created via the Superstaq API.



Classes
-------

.. autoapisummary::

   general_superstaq.job.Endian
   general_superstaq.job.Job


Module Contents
---------------

.. py:class:: Endian

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Endianness to use when mapping quantum objects to matrices, state vectors, and bitstrings.


   .. py:attribute:: BIG
      :value: 'big'



   .. py:attribute:: LITTLE
      :value: 'little'



.. py:class:: 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.


   .. 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
      :raises cancellations were unsuccessful.:



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

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



   .. py:method:: 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`)

      :param index: The circuit index for which to update counts.
      :param 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}`.



   .. py:method:: target() -> str

      Gets the Superstaq target associated with this job.

      :returns: The target to which this job was submitted.

      :raises ~general_superstaq.SuperstaqServerException: If unable to get 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:method:: 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.

      :param index: An optional index of the specific circuit to wait for (otherwise waits for all
                    circuits to complete).
      :param timeout_seconds: The total number of seconds to poll for.
      :param polling_seconds: The interval with which to poll.



   .. py:attribute:: STATUS_PRIORITY_ORDER


   .. py:attribute:: endianness


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