xanadu-cloud-client 0.3.2
XCC is a Python API and CLI for the Xanadu Cloud.
License: Apache License 2.0

.. image:: https://raw.githubusercontent.com/XanaduAI/xanadu-cloud-client/main/docs/_static/xcc_title.svg
    :alt: XCC
    :height: 65
    :width: 100%

The `Xanadu Cloud Client <https://xanadu-cloud-client.readthedocs.io>`_ (XCC) is
a Python API and CLI for the Xanadu Cloud.

.. inclusion-marker-for-features-start

Features
--------

* *Simple*. Easy to setup, explore, and use.

* *Efficient*. Lazy fetching and caching by default.

* *Structured*. Parse Xanadu Cloud responses into JSON or Python objects.

.. inclusion-marker-for-features-end
.. inclusion-marker-for-installation-start

Installation
-------------

The XCC requires Python version 3.7 or above. Installation of the XCC, as well
as all dependencies, can be done using pip:

.. code-block:: console

    pip install xanadu-cloud-client

.. inclusion-marker-for-installation-end
.. inclusion-marker-for-setup-start

Setup
-----

To use the XCC, a Xanadu Cloud API key (or equivalent JWT refresh token) is
required. There are several ways to register your API key with the XCC:

1.  Save your API key to the XCC configuration file using the CLI:

    .. code-block:: console

        xcc config set REFRESH_TOKEN "Xanadu Cloud API key goes here"

2.  Set the ``XANADU_CLOUD_REFRESH_TOKEN`` environment variable:

    .. code-block:: console

        export XANADU_CLOUD_REFRESH_TOKEN="Xanadu Cloud API key goes here"

3.  Save your API key to the XCC configuration file using the Python API:

    .. code-block:: python

        import xcc

        settings = xcc.Settings(REFRESH_TOKEN="Xanadu Cloud API key goes here")
        settings.save()

Afterwards, you can verify that your API key was set correctly using either:

1.  The CLI:

    .. code-block:: console

        $ xcc ping
        Successfully connected to the Xanadu Cloud.

2.  The Python API:

    .. code-block:: console

        import xcc

        connection = xcc.Connection.load()
        assert connection.ping().ok

.. inclusion-marker-for-setup-end
.. inclusion-marker-for-tutorial-start

Tutorial
--------

The following tutorial illustrates a workflow for submitting a job to the Xanadu
Cloud using the CLI. For more detailed usage instructions, use ``--help`` or
refer to the Python API documentation.

1.  Before submitting a job, it is a good idea to check which devices are
    currently accepting jobs on the Xanadu Cloud:

    .. code-block:: console

        $ xcc device list --status online

    .. code-block:: json

        [
            {
                "target": "simulon_gaussian",
                "status": "online"
            },
            {
                "target": "X8_01",
                "status": "online"
            }
        ]

2.  Suppose that the ``simulon_gaussian`` device is of interest. The capabilities,
    operating conditions, and other properties of a device can be queried by
    supplying the appropriate flag to the `xcc device get` command:

    .. code-block:: console

        $ xcc device get simulon_gaussian --availability

    .. code-block:: json

        {
            "monday": [
                "00:00:00+00:00",
                "23:59:59+00:00"
            ],
            "tuesday": [
                "00:00:00+00:00",
                "23:59:59+00:00"
            ],
            "wednesday": [
                "00:00:00+00:00",
                "23:59:59+00:00"
            ],
            "thursday": [
                "00:00:00+00:00",
                "23:59:59+00:00"
            ],
            "friday": [
                "00:00:00+00:00",
                "23:59:59+00:00"
            ],
            "saturday": [
                "00:00:00+00:00",
                "23:59:59+00:00"
            ],
            "sunday": [
                "00:00:00+00:00",
                "23:59:59+00:00"
            ]
        }

    **Note:** Given that ``simulon_gaussian`` is a simulator, it does not have
    any scheduled downtime for maintenance.

3.  Now, consider a Blackbird script stored in a local file named ``circuit.xbb``:

    .. code-block:: console

        $ cat circuit.xbb
        name example
        version 1.0
        target simulon_gaussian (shots=4)

        MeasureFock() | [0, 1, 2]

    This circuit can be submitted to the ``simulon_gaussian`` device using the
    ``xcc job submit`` command:

    .. code-block:: console

        $ xcc job submit --name example \
            --target simulon_gaussian \
            --language "blackbird:1.0" \
            --circuit "$(cat circuit.xbb)"

    .. code-block:: json

        {
            "id": "4c043f6d-54c7-4915-bbb8-eb1b99c4d88e",
            "name": "example",
            "status": "open",
            "target": "simulon_gaussian",
            "created_at": "2021-09-24 17:52:00.532938+00:00",
            "finished_at": null,
            "running_time": null
        }

    **Note:** Replace ``cat foo.xbb`` with ``Get-Content foo.xbb -Raw`` on Windows PowerShell.

4.  The ID of a job can be used to retrieve additional information about that
    job, including its status and running time. Specifically, the ID can be
    supplied to the `xcc job get` command along with an optional flag:

    .. code-block:: console

        $ xcc job get 4c043f6d-54c7-4915-bbb8-eb1b99c4d88e --status
        complete

    The result of a job can be accessed in a similar way:

    .. code-block:: console

        $ xcc job get 4c043f6d-54c7-4915-bbb8-eb1b99c4d88e --result

    .. code-block:: json

        {
            "output": [
                "[[0 0 0]\n[0 0 0]\n[0 0 0]\n[0 0 0]]"
            ]
        }

.. inclusion-marker-for-tutorial-end

Contributions
-------------

We welcome contributions - simply fork the XCC repository and make a `pull
request <https://help.github.com/articles/about-pull-requests/>`_ containing
your contribution. All contributors to the XCC will be listed as authors on the
releases. See our `changelog <https://github.com/XanaduAI/xanadu-cloud-client/blob/main/.github/CHANGELOG.md>`_
for more details.

We also encourage bug reports, suggestions for new features and enhancements,
and even links to cool projects or applications built on top of the XCC. Visit
the `contributions page <https://github.com/XanaduAI/xanadu-cloud-client/blob/main/.github/CONTRIBUTING.md>`_
to learn more about sharing your ideas with the XCC team.

Support
-------

- **Source Code:** https://github.com/XanaduAI/xanadu-cloud-client
- **Issue Tracker:** https://github.com/XanaduAI/xanadu-cloud-client/issues

If you are having issues, please let us know by posting the issue on our GitHub
issue tracker.

Authors
-------

The XCC is the work of `many contributors
<https://github.com/XanaduAI/xir/graphs/contributors>`_.

.. inclusion-marker-for-license-start

License
--------

The XCC is **free** and **open source**, released under the `Apache License,
Version 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_.

.. inclusion-marker-for-license-end