xcc.Job

class Job(id_: str, connection: xcc.connection.Connection)[source]

Bases: object

Represents a job on the Xanadu Cloud.

Parameters
  • id (str) – ID of the job

  • connection (Connection) – connection to the Xanadu Cloud

Note

For performance reasons, the properties of a job are lazily fetched and stored in a cache. This cache can be cleared at any time by calling Job.clear().

Warning

The xcc.Job class transparently contacts the Xanadu Cloud when an uncached job property is accessed. This means that requesting a job property for the first time may take longer than expected.

Example:

The following example shows how to use the Job class to submit and track a job for a simulator on the Xanadu Cloud. First, a connection is established to the Xanadu Cloud:

>>> import xcc
>>> connection = xcc.Connection.load()

Next, the parameters of the desired job are prepared. At present, this includes the name, target, circuit, and language of the job:

>>> import inspect
>>> name = "example"
>>> target = "simulon_gaussian"
>>> circuit = inspect.cleandoc(
        f"""
        name {name}
        version 1.0
        target {target} (shots=3)
        MeasureFock() | [0, 1, 2, 3]
        """
    )
>>> language = "blackbird:1.0"

The job is then submitted to the Xanadu Cloud using the Job.submit() function:

>>> job = xcc.Job.submit(
        connection,
        name=name,
        target=target,
        circuit=circuit,
        language=language,
    )

At this point, the Xanadu Cloud has received the job; however, it may take some time before the result of the job is available. To wait until the job is finished, a blocking call is made to Job.wait():

>>> job.wait()

Finally, the status, result, running time, etc. of the job are retrieved by accessing the corresponding properties of the job:

>>> job.status
'complete'
>>> job.result
{'output': [array([[0, 0, 0, 0],
   [0, 0, 0, 0],
   [0, 0, 0, 0]])]}
>>> job.running_time
datetime.timedelta(microseconds=123456)

circuit

Returns the circuit of a job.

created_at

Returns when a job was created.

finished

Returns whether this job has finished.

finished_at

Returns when a job finished.

id

Returns the ID of a job.

language

Returns the language of a job.

metadata

Returns the metadata of a job.

name

Returns the name of a job.

overview

Returns an overview of a job.

result

Returns the result of a job.

running_time

Returns the running time of a job.

started_at

Returns when a job started.

status

Returns the current status of a job.

target

Returns the target of a job.

circuit

Returns the circuit of a job.

Returns

circuit of this job

Return type

str

created_at

Returns when a job was created.

Returns

datetime when this job was created

Return type

datetime

finished

Returns whether this job has finished.

Returns

True iff the job status is “cancelled”, “complete”, or “failed”

Return type

bool

finished_at

Returns when a job finished.

Returns

datetime when this job finished

Return type

datetime, optional

id

Returns the ID of a job.

language

Returns the language of a job.

Returns

language of this job

Return type

str

metadata

Returns the metadata of a job.

Returns

metadata of this job

Return type

Mapping[str, Any]

Note

Error details for failed jobs are reported here.

name

Returns the name of a job.

Returns

name of this job

Return type

str, optional

overview

Returns an overview of a job.

Returns

mapping from field names to values for this job as determined by the needs of a Xanadu Cloud user.

Return type

Mapping[str, Any]

result

Returns the result of a job.

Returns

The result of this job.

Return type

Mapping[str, Union[np.ndarray, List[np.ndarray]]]

See also

Implemented in terms of Job.get_result().

Note

NumPy integers will be converted to np.int64 objects to facilitate safer post-processing.

running_time

Returns the running time of a job.

Returns

running time of this job

Return type

timedelta, optional

started_at

Returns when a job started.

Returns

datetime when this job started

Return type

datetime, optional

status

Returns the current status of a job.

Returns

status of this job (“open”, “queued”, “cancelled”, “failed”, “cancel_pending”, or “complete”)

Return type

str

target

Returns the target of a job.

Returns

target of this job

Return type

str

cancel()

Cancels a job.

clear()

Clears the details, circuit, and result caches of a job.

get_result([integer_overflow_protection])

Returns the result of a job.

list(connection[, limit, ids, status])

Returns jobs submitted to the Xanadu Cloud.

submit(connection, name, target, circuit, ...)

Submits a job to the Xanadu Cloud.

wait([delay])

Waits for a job to finish.

cancel() None[source]

Cancels a job.

clear() None[source]

Clears the details, circuit, and result caches of a job.

get_result(integer_overflow_protection: bool = True) Mapping[str, Union[numpy.ndarray, List[numpy.ndarray]]][source]

Returns the result of a job.

Parameters

integer_overflow_protection (bool) – convert all NumPy integers into 64-bit NumPy integers during post-processing; setting this option to False can significantly reduce memory consumption at the risk of introducing bugs during e.g. cubing operations

Returns

The result of this job. Each job result has an “output” key associated with a list of NumPy arrays representing the output of the job; all other keys represent metadata related to the interpretation of the job output.

Return type

Mapping[str, Union[np.ndarray, List[np.ndarray]]]

Raises

TypeError – if the job result is not stored in the .npz file format

Warning

The value returned by this method is not cached.

static list(connection: xcc.connection.Connection, limit: int = 5, ids: Optional[Collection[str]] = None, status: Optional[str] = None) Sequence[xcc.job.Job][source]

Returns jobs submitted to the Xanadu Cloud.

Parameters
  • connection (Connection) – connection to the Xanadu Cloud

  • limit (int) – maximum number of jobs to retrieve

  • ids (Collection[str], optional) – IDs of the jobs to retrieve; if at least one ID is specified, limit will be set to the length of the ID collection

  • status (str, optional) – filter jobs by the given status (if not None)

Returns

jobs which were submitted on the Xanadu Cloud by the user associated with the Xanadu Cloud connection

Return type

Sequence[Job]

static submit(connection: xcc.connection.Connection, name: Optional[str], target: str, circuit: str, language: str) xcc.job.Job[source]

Submits a job to the Xanadu Cloud.

Parameters
  • connection (Connection) – connection to the Xanadu Cloud

  • name (str, optional) – name of the job

  • target (str) – target of the job

  • circuit (str) – circuit of the job

  • language (str) – language of the job

Returns

job submitted to the Xanadu Cloud

Return type

Job

wait(delay: float = 1) None[source]

Waits for a job to finish.

Parameters

delay (float) – number of seconds to wait between polling requests