Integrate Xanadu Cloud Client (#656)

* Replace SF CLI with XCC CLI (#642) * Remove CLI package, tests, and entry point * Remove CLI Sphinx documentation * Restructure account configuration tutorial * Add CLI removal to changelog * Add migration guide for the CLI * Add Windows Powershell equivalent for last CLI example * Duplicate CLI migrations in changelog * Replace Connection class with xcc.Connection (#645) * Delete strawberryfields.api.Connection class and tests * Add XCC to installation requirements * Remove Connection from strawberryfields.api package exports * Replace Connection with xcc.Connection inside strawberryfields.api * Update RemoteEngine to use xcc.Connection * Remove explicit test dependencies on api.Connection * Run Black formatter * Adjust, refactor, and enable RemoteEngine tests * Specify 'optional' part of type hints * Document breaking changes and migrations * Add help entry for 'docs' target * Update PR number * Fix DeviceSpec unit test and restore API mark * Update RemoteEngine.device_spec docstring * Update RemoteEngine.run() docstring * Avoid setting Blackbird name twice in RemoteEngine.run_async() * Replace Python 3.9 syntax for dictionary union * Update DeviceSpec to work with XCC (#644) * update device spec * update tests * minor updates * update tests * fixes from code review * fix compiler in device specs * remove regex * remove pylints * Update strawberryfields/api/devicespec.py Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * Update Result class to work with XCC (#651) * fix result class * fix tests * fix bosonic backend tests * fix samples_dict * fix tests * make format * some minor fixes * Apply suggestions from code review Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * fixes from code review * wrap samples in list * update changelog * Apply suggestions from code review Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * update changelog * add to migration giude * fix docstrings * Apply suggestions from code review Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * suggestions from code review Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * Replace `strawberryfields.api.Job` with `xcc.Job` (#650) * Delete strawberryfields.api.Connection class and tests * Add XCC to installation requirements * Remove Connection from strawberryfields.api package exports * Replace Connection with xcc.Connection inside strawberryfields.api * Update RemoteEngine to use xcc.Connection * Remove explicit test dependencies on api.Connection * Run Black formatter * Adjust, refactor, and enable RemoteEngine tests * Specify 'optional' part of type hints * Document breaking changes and migrations * Add help entry for 'docs' target * Update PR number * Fix DeviceSpec unit test and restore API mark * remove Job class * remove/fix tests * remove invalid job operation example * update raises * use f-strings * Apply suggestions from code review Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * fix job refresh in run-loop * update changelog * mock out job.clear * add XCC intermapping * attempt to get xcc docs to interconnect * update xcc url * Apply suggestions from code review Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * move mocked job * doc change * add Job to migration guide * Update doc/development/migration_guides.rst Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * bump xcc in requirements * fix tests * bump xcc in setup Co-authored-by: Mikhail Andrenkov <M.Andrenkov@gmail.com> Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * Replace configuration module with xcc.Settings (#649) * Delete strawberryfields.api.Connection class and tests * Add XCC to installation requirements * Remove Connection from strawberryfields.api package exports * Replace Connection with xcc.Connection inside strawberryfields.api * Update RemoteEngine to use xcc.Connection * Remove explicit test dependencies on api.Connection * Run Black formatter * Adjust, refactor, and enable RemoteEngine tests * Specify 'optional' part of type hints * Document breaking changes and migrations * Add help entry for 'docs' target * Update PR number * Fix DeviceSpec unit test and restore API mark * Update RemoteEngine.device_spec docstring * Update RemoteEngine.run() docstring * Avoid setting Blackbird name twice in RemoteEngine.run_async() * Remove strawberryfields.configuration module and tests * Add XCC to strawberryfields.about() * Rewrite obsolete SF CLI example using the XCC * Add strawberryfields.configuration migration to changelog * Remove extra blank line from changelog * Add 'Configuration' section to migration guide * Update PR number * Use backslashes in Windows path * Add missing space to changelog indentation * Update XCC job submission example output * Remove trailing comma from XCC example output * Extract API subpackage (#652) * remove api folder * remove api from docs * Update tests/api/conftest.py Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> * update devicespec and result (#653) * Merge master into branch (#654) * Bump tensorflow from 2.5.1 to 2.5.2 in /doc (#648) Bumps [tensorflow](https://github.com/tensorflow/tensorflow) from 2.5.1 to 2.5.2. - [Release notes](https://github.com/tensorflow/tensorflow/releases) - [Changelog](https://github.com/tensorflow/tensorflow/blob/master/RELEASE.md) - [Commits](tensorflow/tensorflow@v2.5.1...v2.5.2) --- updated-dependencies: - dependency-name: tensorflow dependency-type: direct:production ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Bump tensorflow from 2.6.0 to 2.6.1 (#647) Bumps [tensorflow](https://github.com/tensorflow/tensorflow) from 2.6.0 to 2.6.1. - [Release notes](https://github.com/tensorflow/tensorflow/releases) - [Changelog](https://github.com/tensorflow/tensorflow/blob/master/RELEASE.md) - [Commits](tensorflow/tensorflow@v2.6.0...v2.6.1) --- updated-dependencies: - dependency-name: tensorflow dependency-type: direct:production ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Josh Izaac <josh146@gmail.com> * Use refactored gaussian gate from The Walrus (#646) * refactor [tfbackend/ops] - gaussian_gate_matrix: use new tw signature * requirement [thewalrus] - point to built wheel from branch * requirement [docs] - use dev version of the walrus * fix [docs/requirements] - use python3.7 for docs * fix [tfbackend/ops] - single_gaussian_gate_matrix: pass new params to tw function * update [worflows/docs] - use sphinx-action at xanadu with python 3.8 * requirements [docs] - use python3.8 wheel Co-authored-by: Theodor <theodor@xanadu.ai> * remove one tf requirement * remove repo-token Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Josh Izaac <josh146@gmail.com> Co-authored-by: Sebastián Duque Mesa <675763+sduquemesa@users.noreply.github.com> * remove fill_template calls (#655) * fix codefactor issues * fix another codefactor issue * make format * Apply suggestions from code review Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> Co-authored-by: Mikhail Andrenkov <Mandrenkov@users.noreply.github.com> Co-authored-by: Mikhail Andrenkov <M.Andrenkov@gmail.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Josh Izaac <josh146@gmail.com> Co-authored-by: Sebastián Duque Mesa <675763+sduquemesa@users.noreply.github.com>
XanaduAI · Nov 19, 2021 · 8721cb3 · 8721cb3
1 parent d7a4ec4
commit 8721cb3
Show file tree

Hide file tree

Showing 43 changed files with 1,215 additions and 4,207 deletions.
diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md
@@ -26,7 +26,7 @@
   state_out = eng.run(prog).state.ket()
   ```
 
-  Note that in order to update the parameter `S` by using its gradient, you cannot use gradient 
+  Note that in order to update the parameter `S` by using its gradient, you cannot use gradient
   descent directly (as the unitary would not be symplectic after the update). Please use the
   function `sf.backends.tfbackend.update_symplectic` which is designed specifically for this purpose.
 
@@ -75,6 +75,259 @@
   two separate real parameters.
   [(#441)](https://github.com/XanaduAI/strawberryfields/pull/441)
 
+* The `sf` CLI has been removed in favour of the
+  [Xanadu Cloud Client](https://github.com/XanaduAI/xanadu-cloud-client).
+  [(#642)](https://github.com/XanaduAI/strawberryfields/pull/642)
+
+  1. Configuring account credentials using:
+
+      * Strawberry Fields v0.19.0
+
+        ```console
+        $ sf configure --token "foo"
+        ```
+
+      * Strawberry Fields v0.20.0
+
+        ```console
+        $ xcc config set REFRESH_TOKEN "foo"
+        Successfully updated REFRESH_TOKEN setting to 'foo'.
+        ```
+
+  2. Verifying your connection to the Xanadu Cloud using:
+
+      * Strawberry Fields v0.19.0
+
+        ```console
+        $ sf --ping
+        You have successfully authenticated to the platform!
+        ```
+
+      * Strawberry Fields v0.20.0
+
+        ```console
+        $ xcc ping
+        Successfully connected to the Xanadu Cloud.
+        ```
+
+  3. Submitting a Blackbird circuit to the Xanadu Cloud using:
+
+      * Strawberry Fields v0.19.0
+
+        ```console
+        $ # Version 0.19.0
+        $ sf run "foo.xbb"
+        Executing program on remote hardware...
+        2021-11-02 03:04:05,06 - INFO - The device spec X8_01 has been successfully retrieved.
+        2021-11-02 03:04:05,07 - INFO - Compiling program for device X8_01 using compiler Xunitary.
+        2021-11-02 03:04:05,08 - INFO - Job b185a63c-f302-4adb-acf8-b6e4e413c11d was successfully submitted.
+        2021-11-02 03:04:05,09 - INFO - The remote job b185a63c-f302-4adb-acf8-b6e4e413c11d has been completed.
+        [[0 0 0 0]
+        [0 0 0 0]
+        [0 0 0 0]
+        [0 0 0 0]]
+        ```
+
+      * Strawberry Fields v0.20.0
+
+        ```console
+        $ xcc job submit --name "bar" --target "X8_01" --circuit "$(cat foo.xbb)"
+        {
+            "id": "0b0f5a46-46d8-4157-8005-45a4764361ba",  # Use this ID below.
+            "name": "bar",
+            "status": "open",
+            "target": "X8_01",
+            "language": "blackbird:1.0",
+            "created_at": "2021-11-02 03:04:05,10",
+            "finished_at": null,
+            "running_time": null,
+            "metadata": {}
+        }
+        $ xcc job get 0b0f5a46-46d8-4157-8005-45a4764361ba --result
+        {
+            "output": [
+                "[[0 0 0 0]\n[0 0 0 0]\n[0 0 0 0]\n[0 0 0 0]]"
+            ]
+        }
+        ```
+
+* The `sf.api.Connection` class has been replaced with the
+  [xcc.Connection](https://xanadu-cloud-client.readthedocs.io/en/stable/api/xcc.Connection.html)
+  class.
+  [(#645)](https://github.com/XanaduAI/strawberryfields/pull/645)
+
+  Previously, in Strawberry Fields v0.19.0, an `sf.RemoteEngine` can be
+  instantiated with a custom Xanadu Cloud connection as follows:
+
+  ```python
+  import strawberryfields as sf
+  import strawberryfields.api
+
+  connection = strawberryfields.api.Connection(
+    token="Xanadu Cloud API key goes here",
+    host="platform.strawberryfields.ai",
+    port=443,
+    use_ssl=True,
+  )
+  engine = sf.RemoteEngine("X8", connection=connection)
+  ```
+
+  In Strawberry Fields v0.20.0, the same result can be achieved using
+  ```python
+  import strawberryfields as sf
+  import xcc
+
+  connection = xcc.Connection(
+    refresh_token="Xanadu Cloud API key goes here",  # See "token" argument above.
+    host="platform.strawberryfields.ai",
+    port=443,
+    tls=True,                                        # See "use_ssl" argument above.
+  )
+  engine = sf.RemoteEngine("X8", connection=connection)
+  ```
+
+* The `sf.configuration` module has been replaced with the
+  [xcc.Settings](https://xanadu-cloud-client.readthedocs.io/en/stable/api/xcc.Settings.html)
+  class.
+  [(#649)](https://github.com/XanaduAI/strawberryfields/pull/649)
+
+  This means that Xanadu Cloud credentials are now stored in exactly one
+  location, the path to which depends on your operating system:
+
+  1. Windows: `C:\Users\%USERNAME%\AppData\Local\Xanadu\xanadu-cloud\.env`
+
+  2. MacOS: `/home/$USER/Library/Application\ Support/xanadu-cloud/.env`
+
+  3. Linux: `/home/$USER/.config/xanadu-cloud/.env`
+
+  The format of the configuration file has also changed to [.env](https://saurabh-kumar.com/python-dotenv/)
+  and the names of some fields have been updated. For example,
+
+  ```toml
+  # Strawberry Fields v0.19.0 (config.toml)
+  [api]
+  authentication_token = "Xanadu Cloud API key goes here"
+  hostname = "platform.strawberryfields.ai"
+  port = 443
+  use_ssl = true
+  ```
+
+  is equivalent to
+
+  ```python
+  # Strawberry Fields v0.20.0 (.env)
+  XANADU_CLOUD_REFRESH_TOKEN='Xanadu Cloud API key goes here'
+  XANADU_CLOUD_HOST='platform.strawberryfields.ai'
+  XANADU_CLOUD_PORT=443
+  XANADU_CLOUD_TLS=True
+  ```
+
+  Similarly, the names of the configuration environment variables have changed from
+
+  ```bash
+  # Strawberry Fields v0.19.0
+  export SF_API_AUTHENTICATION_TOKEN="Xanadu Cloud API key goes here"
+  export SF_API_HOSTNAME="platform.strawberryfields.ai"
+  export SF_API_PORT=443
+  export SF_API_USE_SSL=true
+  ```
+
+  to
+
+  ```bash
+  # Strawberry Fields v0.20.0
+  export XANADU_CLOUD_REFRESH_TOKEN="Xanadu Cloud API key goes here"
+  export XANADU_CLOUD_HOST="platform.strawberryfields.ai"
+  export XANADU_CLOUD_PORT=443
+  export XANADU_CLOUD_TLS=true
+  ```
+
+  Finally, `strawberryfields.store_account()` has been replaced such that
+
+  ```python
+  # Strawberry Fields v0.19.0
+  import strawberryfields as sf
+  sf.store_account("Xanadu Cloud API key goes here")
+  ```
+
+  becomes
+
+  ```python
+  # Strawberry Fields v0.20.0
+  import xcc
+  xcc.Settings(REFRESH_TOKEN="Xanadu Cloud API key goes here").save()
+  ```
+
+* The `sf.api.Job` class has been replaced with the
+  [xcc.Job](https://xanadu-cloud-client.readthedocs.io/en/stable/api/xcc.Job.html)
+  class.
+  [(#650)](https://github.com/XanaduAI/strawberryfields/pull/650)
+
+  A `Job` object is returned when running jobs asynchronously. In previous versions of Strawberry
+  Fields (v0.19.0 and lower), the `Job` object can be used as follows:
+
+  ```pycon
+  >>> job = engine.run_async(program, shots=1)
+  >>> job.status
+  'queued'
+  >>> job.result
+  InvalidJobOperationError
+  >>> job.refresh()
+  >>> job.status
+  'complete'
+  >>> job.result
+  [[0 1 0 2 1 0 0 0]]
+  ```
+
+  In Strawberry Fields v0.20.0, the `Job` object works slightly differently:
+
+  ```pycon
+  >>> job = engine.run_async(program, shots=1)
+  >>> job.status
+  'queued'
+  >>> job.wait()
+  >>> job.status
+  'complete'
+  >>> job.result
+  {'output': [array([[0 1 0 2 1 0 0 0]])]}
+  ```
+
+  The `job.wait()` method is a blocking method that will wait for the job to finish. Alternatively,
+  `job.clear()` can be called to clear the cache, allowing `job.status` to re-fetch the job status.
+
+* The `sf.api.Result` class has been updated to support the Xanadu Cloud Client integration.
+  [(#651)](https://github.com/XanaduAI/strawberryfields/pull/651)
+
+  While `Result.samples` should return the same type and shape as before, the `Result.all_samples`
+  property has been renamed to `Result.samples_dict` and returns the samples as a dictionary with
+  corresponding measured modes as keys.
+
+  ```pycon
+  >>> res = eng.run(prog, shots=3)
+  >>> res.samples
+  array([[1, 0], [0, 1], [1, 1]])
+  >>> res.samples_dict
+  {0: [np.array([1, 0, 1])], 1: [np.array([0, 1, 1])]}
+  ```
+
+  The samples dictionary is only accessible for simulators.
+
+* The `sf.api.DeviceSpec` class has been updated to support the Xanadu Cloud Client integration.
+  [(#644)](https://github.com/XanaduAI/strawberryfields/pull/644)
+
+  It now works as a container for a device specification dictionary. There are no more API
+  connection usages, and `DeviceSpec.target` is retrieved from the device specification rather than
+  passed at initialization.
+
+* The `api` subpackage has been removed and the contained `DeviceSpec` and `Result` classes have
+  been moved to the root `strawberryfields` folder. They can now be imported as follows:
+
+  ```python
+  import strawberryfields  as sf
+  # sf.DeviceSpec
+  # sf.Result
+  ```
+
 <h3>Bug fixes</h3>
 
 <h3>Documentation</h3>
@@ -83,7 +336,8 @@
 
 This release contains contributions from (in alphabetical order):
 
-Mikhail Andrenkov, Sebastián Duque Mesa, Filippo Miatto, Nicolás Quesada, Antal Száva, Yuan Yao.
+Mikhail Andrenkov, Sebastián Duque Mesa, Theodor Isacsson, Filippo Miatto, Nicolás Quesada, Antal
+Száva, Yuan Yao.
 
 # Release 0.19.0 (current release)
 

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -10,6 +10,5 @@ jobs:
     - uses: XanaduAI/sphinx-action@master
       with:
         docs-folder: "doc/"
-        repo-token: "${{ secrets.GITHUB_TOKEN }}"
         pre-build-command: "apt install -y graphviz && pip3 install -r requirements.txt && pip3 install ."
         build-command: "sphinx-build -b html . _build -W --keep-going"
diff --git a/Makefile b/Makefile
@@ -8,6 +8,7 @@ help:
 	@echo "  install            to install Strawberry Fields"
 	@echo "  wheel              to build the Strawberry Fields wheel"
 	@echo "  dist               to package the source distribution"
+	@echo "  docs               to generate the Sphinx documentation"
 	@echo "  clean              to delete all temporary, cache, and build files"
 	@echo "  clean-docs         to delete all built documentation"
 	@echo "  format             to run black formatting"
@@ -47,6 +48,7 @@ clean:
 	rm -rf dist
 	rm -rf build
 
+.PHONY : docs
 docs:
 	make -C doc html
 

diff --git a/default_config.toml b/default_config.toml
diff --git a/doc/code/sf_api.rst b/doc/code/sf_api.rst