Add Getting Started page

docs/apidocs/aer.rst

@@ -15,5 +15,4 @@ Qiskit Aer API Reference
     aer_pulse
     aer_utils
     aer_quantum_info
-    circuit
-    parallel
+    circuit

docs/conf.py

@@ -25,9 +25,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
 
 """
 Sphinx documentation builder
@@ -38,13 +38,17 @@
 # Set env flag so that we can doc functions that may otherwise not be loaded
 # see for example interactive visualizations in qiskit.visualization.
 os.environ['QISKIT_DOCS'] = 'TRUE'
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- Project information -----------------------------------------------------
 project = 'Qiskit Aer'
 copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team"  # pylint: disable=redefined-builtin
 author = 'Qiskit Development Team'
 
 import qiskit_sphinx_theme
+from custom_directives import (
+    CustomCalloutItemDirective
+)
 
 # The short X.Y version
 version = '0.13.0'
@@ -75,6 +79,7 @@
     'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.intersphinx',
     'nbsphinx',
+    "sphinx_design",
     'qiskit_sphinx_theme'
 ]
 
@@ -157,3 +162,7 @@
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "qiskit": ("https://qiskit.org/documentation/", None),
 }
+
+# -- Extension configuration -------------------------------------------------
+def setup(app):
+    app.add_directive("customcalloutitem", CustomCalloutItemDirective)

docs/custom_directives.py

@@ -0,0 +1,68 @@
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import StringList
+from docutils import nodes
+
+try:
+    FileNotFoundError
+except NameError:
+    FileNotFoundError = IOError
+
+
+class CustomCalloutItemDirective(Directive):
+    option_spec = {
+        "header": directives.unchanged,
+        "description": directives.unchanged,
+        "button_link": directives.unchanged,
+        "button_text": directives.unchanged,
+    }
+
+    def run(self):
+        try:
+            if "description" in self.options:
+                description = self.options["description"]
+            else:
+                description = ""
+
+            if "header" in self.options:
+                header = self.options["header"]
+            else:
+                raise ValueError("header not doc found")
+
+            if "button_link" in self.options:
+                button_link = self.options["button_link"]
+            else:
+                button_link = ""
+
+            if "button_text" in self.options:
+                button_text = self.options["button_text"]
+            else:
+                button_text = ""
+
+        except FileNotFoundError as e:
+            print(e)
+            return []
+        except ValueError as e:
+            print(e)
+            raise
+            return []
+
+        callout_rst = CALLOUT_TEMPLATE.format(
+            description=description, header=header, button_link=button_link, button_text=button_text
+        )
+        callout_list = StringList(callout_rst.split("\n"))
+        callout = nodes.paragraph()
+        self.state.nested_parse(callout_list, self.content_offset, callout)
+        return [callout]
+
+
+CALLOUT_TEMPLATE = """
+.. raw:: html
+
+    <div class="col-md-6">
+        <div class="text-container">
+            <h3>{header}</h3>
+            <p class="body-paragraph">{description}</p>
+            <a class="btn with-right-arrow callout-button" href="{button_link}">{button_text}</a>
+        </div>
+    </div>
+"""

docs/getting_started.rst

@@ -0,0 +1,211 @@
+:orphan:
+
+###############
+Getting started
+###############
+
+Installation
+============
+Qiskit Aer depends on the main Qiskit package which has its own
+`Qiskit Getting Started <https://qiskit.org/documentation/getting_started.html>`__ detailing the
+installation options for Qiskit and its supported environments/platforms. You should refer to
+that first. Then the information here can be followed which focuses on the additional installation
+specific to Qiskit Aer.
+
+
+.. tab-set::
+
+    .. tab-item:: Start locally
+
+      The simplest way to get started is to follow the getting started 'Start locally' for Qiskit
+      here `Qiskit Getting Started <https://qiskit.org/documentation/getting_started.html>`__
+
+      In your virtual environment where you installed Qiskit simply add ``aer`` to the
+      extra list in a similar manner to how the extra ``visualization`` support is installed for
+      Qiskit, i.e:
+
+      .. code:: sh
+
+         pip install qiskit-aer
+
+      **Installing GPU support**
+
+      In order to install and run the GPU supported simulators on Linux, you need CUDA® 10.1 or newer 
+      previously installed. CUDA® itself would require a set of specific GPU drivers. 
+      Please follow CUDA® installation procedure in the NVIDIA® `web <https://www.nvidia.com/drivers>`_.  
+
+      If you want to install our GPU supported simulators, you have to install this other package:
+
+      .. code:: sh
+
+         pip install qiskit-aer-gpu
+
+      This will overwrite your current qiskit-aer package installation giving you the same functionality found 
+      in the canonical qiskit-aer package, plus the ability to run the GPU supported 
+      simulators: statevector, density matrix, and unitary.
+
+      *Note: This package is only available on x86_64 Linux. 
+      For other platforms that have CUDA support you will have to build from source.* 
+
+
+    .. tab-item:: Install from source
+
+
+      Installing Qiskit Aer from source allows you to access the most recently
+      updated version under development instead of using the version in the Python Package
+      Index (PyPI) repository. This will give you the ability to inspect and extend
+      the latest version of the Qiskit Aer code more efficiently.
+
+      Since Qiskit Aer depends on Qiskit, and its latest changes may require new or changed
+      features of Qiskit, you should first follow Qiskit's `"Install from source"` instructions
+      here `Qiskit Getting Started <https://qiskit.org/documentation/getting_started.html>`__
+
+      .. raw:: html
+
+         <h2>Installing Qiskit Aer from Source</h2>
+
+
+      Clone the ``Qiskit Aer`` repo via *git*.
+
+      .. code:: sh
+
+         git clone https://github.com/Qiskit/qiskit-aer
+
+      The common dependencies can then be installed via *pip*, using the ``requirements-dev.txt`` file, e.g.:
+
+      .. code:: sh
+
+         cd qiskit-aer
+         pip install -r requirements-dev.txt
+
+      As any other Python package, we can install from source code by just running:
+
+      .. code:: sh
+
+         qiskit-aer$ pip install .
+
+      This will build and install ``Aer`` with the default options which is
+      probably suitable for most of the users. There’s another Pythonic
+      approach to build and install software: build the wheels distributable
+      file.
+
+      .. code:: sh
+
+         qiskit-aer$ pip install build
+         qiskit-aer$ python -I -m build --wheel
+
+
+      See `here <https://github.com/Qiskit/qiskit-aer/blob/main/CONTRIBUTING.md#install-from-source>`__ 
+      for detailed installation information.
+
+      .. raw:: html
+
+         <h2>Building with GPU support</h2>
+
+      Qiskit Aer can exploit GPU’s horsepower to accelerate some simulations,
+      specially the larger ones. GPU access is supported via CUDA® (NVIDIA®
+      chipset), so to build with GPU support, you need to have CUDA® >= 10.1
+      preinstalled. See install instructions
+      `here <https://developer.nvidia.com/cuda-toolkit-archive>`__ Please note
+      that we only support GPU acceleration on Linux platforms at the moment.
+
+      Once CUDA® is properly installed, you only need to set a flag so the
+      build system knows what to do:
+
+      .. code:: sh
+
+         AER_THRUST_BACKEND=CUDA
+
+      For example,
+
+      .. code:: sh
+
+         qiskit-aer$ python ./setup.py bdist_wheel -- -DAER_THRUST_BACKEND=CUDA
+
+      See `here <https://github.com/Qiskit/qiskit-aer/blob/main/CONTRIBUTING.md>`__ 
+      for detailed GPU support information.
+
+      .. raw:: html
+
+         <h3>Building with MPI support</h3>
+
+      Qiskit Aer can parallelize its simulation on the cluster systems by
+      using MPI. This can extend available memory space to simulate quantum
+      circuits with larger number of qubits and also can accelerate the
+      simulation by parallel computing. To use MPI support, any MPI library
+      (i.e. OpenMPI) should be installed and configured on the system.
+
+      Qiskit Aer supports MPI both with and without GPU support. Currently
+      following simulation methods are supported to be parallelized by MPI.
+
+      -  statevector
+      -  density_matrix
+      -  unitary
+
+      To enable MPI support, the following flag is needed for build system
+      based on CMake.
+
+      .. code:: sh
+
+         AER_MPI=True
+
+      For example,
+
+      .. code:: sh
+
+         qiskit-aer$ python ./setup.py bdist_wheel -- -DAER_MPI=True
+
+      See `here <https://github.com/Qiskit/qiskit-aer/blob/main/CONTRIBUTING.md>`__ 
+      for detailed MPI support information.
+
+
+Simulating your first quantum program with Qiskit Aer
+=====================================================
+Now that you have Qiskit Aer installed, you can start simulating a quantum circuit. 
+Here is a basic example:
+
+.. code:: python
+
+  import qiskit
+  from qiskit_aer import AerSimulator
+
+  # Generate 3-qubit GHZ state
+  circ = qiskit.QuantumCircuit(3)
+  circ.h(0)
+  circ.cx(0, 1)
+  circ.cx(1, 2)
+  circ.measure_all()
+
+  # Construct an ideal simulator
+  aersim = AerSimulator()
+
+  # Perform an ideal simulation
+  result_ideal = qiskit.execute(circ, aersim).result()
+  counts_ideal = result_ideal.get_counts(0)
+  print('Counts(ideal):', counts_ideal)
+  # Counts(ideal): {'000': 493, '111': 531}
+
+Ready to get going?...
+======================
+
+.. raw:: html
+
+   <div class="tutorials-callout-container">
+      <div class="row">
+
+.. customcalloutitem::
+   :description: Find out about Qiskit Aer
+   :header: Dive into the tutorials
+   :button_link:  ./tutorials/index.html
+   :button_text: Qiskit Aer tutorials
+
+.. raw:: html
+
+      </div>
+   </div>
+
+
+.. Hiding - Indices and tables
+   :ref:`genindex`
+   :ref:`modindex`
+   :ref:`search`

docs/howtos/index.rst

@@ -0,0 +1,18 @@
+###########################
+Qiskit Aer How-To Guides
+###########################
+
+This section of the documentation provides concrete step-by-step instructions for how to
+do specific useful actions in Qiskit Aer.
+
+.. toctree::
+    :caption: How to...
+    :maxdepth: 1
+    :glob:
+
+    *
+
+.. Hiding - Indices and tables
+   :ref:`genindex`
+   :ref:`modindex`
+   :ref:`search`