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)
Attributes
Returns the circuit of a job.
Returns when a job was created.
Returns whether this job has finished.
Returns when a job finished.
Returns the ID of a job.
Returns the language of a job.
Returns the metadata of a job.
Returns the name of a job.
Returns an overview of a job.
Returns the result of a job.
Returns the running time of a job.
Returns when a job started.
Returns the current status of a job.
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
Methods
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.
- 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 collectionstatus (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