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

`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]]]

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.

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

api/xcc.Job

Download Python script

Download Notebook

View on GitHub

xcc.Job¶

Attributes

Methods

Contents