Qiskit
******

cuQuantum Appliance contains Qiskit and :doc:`cusvaer <./cusvaer>`.
cusvaer is seamlessly integrated into Qiskit Aer, so that users are able to use run multi-node simulations through Qiskit Aer without any modifications to their source code.

For details of the cusvaer backend solver, please refer to :doc:`cusvaer<./cusvaer>`.

Getting started
===============

The following python script is an example to run Greenberger–Horne–Zeilinger (GHZ) circuit.

.. code-block:: python

  from qiskit import QuantumCircuit, transpile
  from qiskit_aer import Aer

  def create_ghz_circuit(n_qubits):
      circuit = QuantumCircuit(n_qubits)
      circuit.h(0)
      for qubit in range(n_qubits - 1):
          circuit.cx(qubit, qubit + 1)
      return circuit

  simulator = Aer.get_backend('aer_simulator_statevector')
  circuit = create_ghz_circuit(n_qubits=20)
  circuit.measure_all()
  circuit = transpile(circuit, simulator)
  job = simulator.run(circuit)
  result = job.result()

  print(result.get_counts())
  print(f'backend: {result.backend_name}')

This script works with Qiskit Aer.  When the script is executed in the current version of cuQuantum Appliance, the multi-node backend is automatically selected and runs the simulation.  The backend name is ``"cusvaer_simulator_statevector"``.

.. code-block:: bash

   $ python ghz.py
   {'00000000000000000000': 493, '11111111111111111111': 531}
   backend: cusvaer_simulator_statevector


By launching a script with mpirun, simulation will be distributed to multiple processes.  In the following examples, two processes are used for simulation, and result will be output twice.

.. code-block:: bash

   $ mpirun -n 2 python ghz.py
   {'00000000000000000000': 536, '11111111111111111111': 488}
   cusvaer_simulator_statevector
   {'00000000000000000000': 536, '11111111111111111111': 488}
   cusvaer_simulator_statevector

By adding the lines shown below, the process where ``mpi_rank == 0`` is selected to output the result.

.. code-block:: python

   if result.mpi_rank == 0:
       print(result.get_counts())
       print(f'backend: {result.backend_name}')

.. code-block:: bash

   $ mpirun -n 2 python ghz.py
   {'00000000000000000000': 532, '11111111111111111111': 492}
   cusvaer_simulator_statevector

.. note::

  The ``qiskit_aer.Aer`` object is available in Qiskit 1.0. For previous versions of Qiskit, ``qiskit.Aer`` works in the same way.

.. note::

  GHZ circuit is used here as an example, which does not mean for demonstrating performance.  It is known that the GHZ circuit is too shallow to show good scaling when simulation is distributed to multiple-GPUs and/or multiple-nodes.


Selecting simulator
===================

The current version of Qiskit Aer installed in cuQuantum Appliance is extended to instantiate the cusvaer backend solver when all the following conditions are met:

.. code-block:: python

    cusvaer_enable == True

    method == "statevector" or method == "automatic"

    noise_model == None

``cusvaer_enable`` is an extension to Qiskit Aer that enables cusvaer.  The default value is ``True``.  The ``method`` and ``noise_model`` are options provided by Qiskit Aer.  cusvaer is selected only if the ``noise_model`` option is ``None`` as the first release of cusvaer does not support noise model.

cusvaer-specific options
========================

Please refer to :ref:`cusvaer options <cusvaerOptions-label>`.

Modifications for Qiskit Aer options
====================================

The following table shows the modified and added options to Qiskit Aer.

.. list-table::
  :widths: 35 65

  * - Option
    - Description
  * - ``cusvaer_enable``
    - If set to ``True``, cusvaer is enabled. Otherwise, Qiskit Aer simulators are used.  The default value is set to ``True``.
  * - ``device``
    - The default value is changed to ``"GPU"``.
  * - ``cuStateVec_enable``
    - The default value is changed to ``True``.

Interoperability with mpi4py
============================

`mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ is interoperable with cusvaer backend.  Please refer to :ref:`Interoperability with mpi4py <mpi4py-label>` for details.

Limitations
===========

The current release version has the following limitations:

* Noise model and noisy circuit simulations are not supported.
* Simulations are executed in serial even if Qiskit Aer's parallel simulation options (e.g., ``batched_shots_gpu``, ``batched_shots_gpu_max_qubits``) are provided.
* Single-process multi-GPU simulation is not supported.  Users need to launch multiple MPI processes even in a single node.