Cirq
****

Notice
======

We only document what is different from Google's ``qsimcirq``.
For more information, please review `Google's Documentation <https://quantumai.google/reference/python/qsimcirq/QSimOptions>`_.
For information on using qsim, refer to `its documentation <https://quantumai.google/qsim>`_.
For getting started using the NVIDIA cuQuantum Appliance with Cirq, visit the :doc:`overview on NGC <./index>`.

.. _appliance-cirq:

API Reference
=============

``qsimcirq.QSimOptions``
------------------------

.. code-block:: python

    class QSimOptions:
        max_fused_gate_size: int = 4
        max_fused_diagonal_gate_size: int = -1
        cpu_threads: int = 1
        ev_noisy_repetitions: int = 1
        disable_gpu: bool = False
        gpu_mode: Union[int, Sequence[int]] = (0,)
        gpu_network: int = 0
        gpu_state_threads: int = 512
        gpu_data_blocks: int = 16
        verbosity: int = 0
        denormals_are_zeros: bool = False
        n_subsvs: int = -1
        use_sampler: Union[bool, None] = None

----

.. include:: .cirq.rst-inc

.. list-table::
    :widths: 10 100

    * - Keyword
      - Description
    * - ``gpu_mode``
      - |gpu_mode|
    * - ``n_subsvs``
      - |n_subsvs|
    * - ``use_sampler``
      - |use_sampler|
    * - ``gpu_network``
      - |gpu_network|
    * - ``disable_gpu``
      - |disable_gpu|
    * - ``max_fused_diagonal_gate_size``
      - |max_fused_diagonal_gate_size|

----

.. note::
   The NVIDIA cuQuantum Appliance provides GPU and multi-GPU simulators.  If you need to run a CPU simulator in qsimcirq, it's recommended to use the qsimcirq packages released by `Google Quantum AI team <https://quantumai.google/qsim/install_qsimcirq>`_.  If you need to run a CPU backend installed in NVIDIA cuQuantum Appliance, please specify options ``qsimcirq.QSimOptions(disable_gpu=True)``.

Some examples
~~~~~~~~~~~~~

.. code-block:: python

   options = qsimcirq.QSimOptions(gpu_mode=1)      # use cuStateVec (single-GPU) backend
   options = qsimcirq.QSimOptions(gpu_mode=(0,))   # use multi-GPU backend with GPU #0
   options = qsimcirq.QSimOptions(gpu_mode=2)      # use multi-GPU backend with the first 2 devices
   options = qsimcirq.QSimOptions(gpu_mode=(0,2))  # use multi-GPU backend with GPU #0 & #2
   options = qsimcirq.QSimOptions(gpu_mode=())     # use multi-GPU backend with GPU #0