Docs updated.

docs/conf.py

@@ -162,6 +162,7 @@
     'matplotlib': ('https://matplotlib.org/stable', None),
     'numpy': ('https://numpy.org/doc/stable', None),
     'scipy': ('https://docs.scipy.org/doc/scipy', None),
+    'iqm_client': ('https://iqm-finland.github.io/iqm-client', None),
 }
 
 extlinks = {

docs/user_guide.rst

@@ -205,9 +205,23 @@ If you have gates involving more than two qubits you need to decompose them befo
 Since routing may add some SWAP gates to the circuit, you will need to decompose the circuit
 again after the routing, unless SWAP is a native gate for the target device.
 
-To ensure that the transpiler is restricted to a specific subset of qubits, you can provide a list of qubits in the ``qubit_subset`` argument such that ancillary qubits will not be added during routing. This is particularly useful when running Quantum Volume benchmarks.
+To ensure that the transpiler is restricted to a specific subset of qubits, you can provide a list
+of qubits in the ``qubit_subset`` argument such that ancillary qubits will not be added during
+routing. This is particularly useful when running Quantum Volume benchmarks.
 
-Additionally, if the target device supports MOVE gates (e.g. IQM Deneb), a final MOVE gate insertion step is performed. Under the hood, this uses the :meth:`transpile_insert_moves`method of the iqm_client library. This method is exposed through :meth:`transpile_insert_moves_into_circuit` which can also be used by advanced users to transpile circuits that have already some MOVE gates in them, or to remove existing MOVE gates from a circuit so the circuit can be reused on a device that does not support them. 
+IQM Star architecture
+^^^^^^^^^^^^^^^^^^^^^
+
+Devices that have the IQM Star architecture (e.g. IQM Deneb) support MOVE gates that are used
+to move quantum states between qubits and computational resonators.
+For these devices a final MOVE gate insertion step must be performed, which introduces
+the computational resonators to the circuit, and routes the two-qubit gates through them using MOVEs.
+
+Under the hood, this uses the :func:`~iqm.iqm_client.transpile.transpile_insert_moves` function of the
+:mod:`iqm_client` library. This method is exposed through :func:`.transpile_insert_moves_into_circuit` which
+can also be used by advanced users to transpile circuits that have already some MOVE gates in them,
+or to remove existing MOVE gates from a circuit so the circuit can be reused on a device that does
+not support them.
 
 Optimization
 ------------
@@ -246,12 +260,13 @@ Running on a real quantum computer
 .. note::
 
    At the moment IQM does not provide a quantum computing service open to the general public.
-   Please contact our `sales team <https://www.meetiqm.com/contact/>`_ to set up your access to an IQM quantum computer.
+   Please contact our `sales team <https://www.meetiqm.com/contact-us/>`_ to set up your access to
+   an IQM quantum computer.
 
 Cirq contains various simulators which you can use to simulate the circuits constructed above.
 In this subsection we demonstrate how to run them on an IQM quantum computer.
 
-Cirq on IQM implements :class:`.IQMSampler`, a subclass of :class:`cirq.work.Sampler`, which is used
+Cirq on IQM provides :class:`.IQMSampler`, a subclass of :class:`cirq.work.Sampler`, which is used
 to execute quantum circuits. Once you have access to an IQM server you can create an :class:`.IQMSampler`
 instance and use its :meth:`~.IQMSampler.run` method to send a circuit for execution and retrieve the results:
 
@@ -277,22 +292,42 @@ The below table summarises the currently available options:
      - Type
      - Example value
      - Description
-   * - `calibration_set_id`
-     - str
+   * - :attr:`calibration_set_id`
+     - :class:`uuid.UUID`
      - "f7d9642e-b0ca-4f2d-af2a-30195bd7a76d"
-     - Indicates the calibration set to use. Defaults to `None`, which means the IQM server will use the best
+     - Indicates the calibration set to use. Defaults to ``None``, which means the IQM server will use the best
        available calibration set automatically.
-   * - `max_circuit_duration_over_t2`
-     - float
+   * - :attr:`compiler_options`
+     - :class:`~iqm.iqm_client.models.CircuitCompilationOptions`
+     - see below
+     - Contains various options that affect the compilation of the quantum circuit into an
+       instruction schedule.
+
+The :class:`~iqm.iqm_client.models.CircuitCompilationOptions` class contains the following attributes (in addition to some
+advanced options described in the API documentation):
+
+.. list-table::
+   :widths: 25 20 25 100
+   :header-rows: 1
+
+   * - Name
+     - Type
+     - Example value
+     - Description
+   * - :attr:`max_circuit_duration_over_t2`
+     - :class:`float` | :class:`None`
      - 1.0
      - Set server-side circuit disqualification threshold. If any circuit in a job is estimated to take longer than the
        shortest T2 time of any qubit used in the circuit multiplied by this value, the server will reject the job.
        Setting this value to ``0.0`` will disable circuit duration check.
        The default value ``None`` means the server default value will be used.
-   * - `heralding_mode`
-     - :py:class:`~iqm_client.models.HeraldingMode`
+   * - :attr:`heralding_mode`
+     - :class:`~iqm.iqm_client.models.HeraldingMode`
      - "zeros"
-     - Heralding mode to use during execution. The default value is "none", "zeros" enables heralding.
+     - Heralding mode to use during execution. The default value is "none", "zeros" enables
+       all-zeros heralding where the circuit qubits are measured before the circuit begins, and the
+       server post-selects and returns only those shots where the heralding measurement yields zeros
+       for all the qubits.
 
 For example if you would like to use a particular calibration set, you can provide it as follows:
 
@@ -301,23 +336,24 @@ For example if you would like to use a particular calibration set, you can provi
    sampler = IQMSampler(iqm_server_url, calibration_set_id="f7d9642e-b0ca-4f2d-af2a-30195bd7a76d")
 
 
-The same applies for `heralding_mode` and `max_circuit_duration_over_t2`. The sampler will by default use an
-:class:`.IQMDevice` created based on architecture data obtained from the server, which is then available in the
-:attr:`.IQMSampler.device` property. Alternatively, the device can be specified directly with the ``device`` argument.
+The sampler will by default use an :class:`.IQMDevice` created based on architecture data obtained
+from the server, which is then available in the :attr:`.IQMSampler.device` property. Alternatively,
+the device can be specified directly with the :attr:`device` argument.
 
 If the IQM server you are connecting to requires authentication, you will also have to use
 `Cortex CLI <https://github.com/iqm-finland/cortex-cli>`_ to retrieve and automatically refresh access tokens,
-then set the ``IQM_TOKENS_FILE`` environment variable to use those tokens.
+then set the :envvar:`IQM_TOKENS_FILE` environment variable to use those tokens.
 See Cortex CLI's `documentation <https://iqm-finland.github.io/cortex-cli/readme.html>`_ for details.
-Alternatively, you can authenticate yourself using the ``IQM_AUTH_SERVER``, ``IQM_AUTH_USERNAME``
-and ``IQM_AUTH_PASSWORD`` environment variables, or pass them as arguments to the constructor of
+Alternatively, you can authenticate yourself using the :envvar:`IQM_AUTH_SERVER`, :envvar:`IQM_AUTH_USERNAME`
+and :envvar:`IQM_AUTH_PASSWORD` environment variables, or pass them as arguments to the constructor of
 :class:`.IQMProvider`, but this approach is less secure and considered deprecated.
 
 When executing a circuit that uses something other than the device qubits, you need to route it first,
 as explained in the :ref:`routing` section above.
 
-Multiple circuits can be submitted to the IQM quantum computer at once using the :meth:`~.IQMSampler.run_iqm_batch` method of :class:`.IQMSampler`.
-This is often faster than executing the circuits individually. Circuits submitted in a batch are still executed sequentially.
+Multiple circuits can be submitted to the IQM quantum computer at once using the
+:meth:`~.IQMSampler.run_iqm_batch` method of :class:`.IQMSampler`.  This is often faster than
+executing the circuits individually. Circuits submitted in a batch are still executed sequentially.
 
 .. code-block:: python
 
@@ -353,7 +389,7 @@ way as those functions.
 
 
 It is also possible to print a run request when it is actually submitted by setting the environment variable
-``IQM_CLIENT_DEBUG=1``.
+:envvar:`IQM_CLIENT_DEBUG=1`.
 
 
 More examples