From 97170bee9b92441c79829bc6bd1be11877d290bd Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 14 Jul 2022 09:53:47 -0400 Subject: [PATCH] Update tab syntax for sphinx-design In #1558 the sphinx plugin sphinx-panel was switched to sphinx-design to enable building the documentation with sphinx >=5.0.0. However, while the build succeeded there were warnings emitted about tabbed directive which was only valid for sphinx-panel. This prevented any tabbed sections in the documentation from being built as sphinx just ignored it (this is why it's best practice to build with -W to make warnings fatal because they're almost always pointing to broken docs). This commit fixes this by migrating the directives to use the syntax from sphinx-design so that we're building the tabs sections of the documentation. Fixes #1566 --- docs/contributing_to_qiskit.rst | 134 +++---- docs/getting_started.rst | 629 ++++++++++++++++---------------- 2 files changed, 385 insertions(+), 378 deletions(-) diff --git a/docs/contributing_to_qiskit.rst b/docs/contributing_to_qiskit.rst index 9955f9682fc0..6bbb24e22b51 100644 --- a/docs/contributing_to_qiskit.rst +++ b/docs/contributing_to_qiskit.rst @@ -696,43 +696,45 @@ from system-wide packages. This way, we avoid inadvertently becoming dependent o particular system configuration. For developers, this also makes it easy to maintain multiple environments (e.g. one per supported Python version, for older versions of Qiskit, etc.). -.. tabbed:: Python venv +.. tab-set:: - All Python versions supported by Qiskit include built-in virtual environment module - `venv `__. + .. tab-item:: Python venv - Start by creating a new virtual environment with ``venv``. The resulting - environment will use the same version of Python that created it and will not inherit installed - system-wide packages by default. The specified folder will be created and is used to hold the environment's - installation. It can be placed anywhere. For more detail, see the official Python documentation, - `Creation of virtual environments `__. + All Python versions supported by Qiskit include built-in virtual environment module + `venv `__. - .. code-block:: sh + Start by creating a new virtual environment with ``venv``. The resulting + environment will use the same version of Python that created it and will not inherit installed + system-wide packages by default. The specified folder will be created and is used to hold the environment's + installation. It can be placed anywhere. For more detail, see the official Python documentation, + `Creation of virtual environments `__. - python3 -m venv ~/.venvs/qiskit-dev + .. code-block:: sh - Activate the environment by invoking the appropriate activation script for your system, which can - be found within the environment folder. For example, for bash/zsh: + python3 -m venv ~/.venvs/qiskit-dev - .. code-block:: sh + Activate the environment by invoking the appropriate activation script for your system, which can + be found within the environment folder. For example, for bash/zsh: - source ~/.venvs/qiskit-dev/bin/activate + .. code-block:: sh - Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections - can be located for your system. + source ~/.venvs/qiskit-dev/bin/activate - .. code-block:: sh + Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections + can be located for your system. - pip install -U pip + .. code-block:: sh -.. tabbed:: Conda + pip install -U pip - For Conda users, a new environment can be created as follows. + .. tab-item:: Conda - .. code-block:: sh + For Conda users, a new environment can be created as follows. + + .. code-block:: sh - conda create -y -n QiskitDevenv python=3 - conda activate QiskitDevenv + conda create -y -n QiskitDevenv python=3 + conda activate QiskitDevenv .. _install-qiskit-terra: @@ -832,84 +834,86 @@ using. Since Aer is a compiled C++ program with a Python interface, there are non-Python dependencies for building the Aer binary which can't be installed universally depending on operating system. -.. tabbed:: Linux +.. tab-set:: + + .. tab-item:: Linux - 3. Install compiler requirements. + 3. Install compiler requirements. - Building Aer requires a C++ compiler and development headers. + Building Aer requires a C++ compiler and development headers. - If you're using Fedora or an equivalent Linux distribution, - install using: + If you're using Fedora or an equivalent Linux distribution, + install using: - .. code:: sh + .. code:: sh - dnf install @development-tools + dnf install @development-tools - For Ubuntu/Debian install it using: + For Ubuntu/Debian install it using: - .. code:: sh + .. code:: sh - apt-get install build-essential + apt-get install build-essential - 4. Install OpenBLAS development headers. + 4. Install OpenBLAS development headers. - If you're using Fedora or an equivalent Linux distribution, - install using: + If you're using Fedora or an equivalent Linux distribution, + install using: - .. code:: sh + .. code:: sh - dnf install openblas-devel + dnf install openblas-devel - For Ubuntu/Debian install it using: + For Ubuntu/Debian install it using: - .. code:: sh + .. code:: sh - apt-get install libopenblas-dev + apt-get install libopenblas-dev -.. tabbed:: macOS + .. tab-item:: macOS - 3. Install dependencies. + 3. Install dependencies. - To use the `Clang `__ compiler on macOS, you need to install - an extra library for supporting `OpenMP `__. You can use `brew `__ - to install this and other dependencies. + To use the `Clang `__ compiler on macOS, you need to install + an extra library for supporting `OpenMP `__. You can use `brew `__ + to install this and other dependencies. - .. code:: sh + .. code:: sh - brew install libomp + brew install libomp - 4. Then install a BLAS implementation; `OpenBLAS `__ - is the default choice. + 4. Then install a BLAS implementation; `OpenBLAS `__ + is the default choice. - .. code:: sh + .. code:: sh - brew install openblas + brew install openblas - Next, install ``Xcode Command Line Tools``. + Next, install ``Xcode Command Line Tools``. - .. code:: sh + .. code:: sh - xcode-select --install + xcode-select --install -.. tabbed:: Windows + .. tab-item:: Windows - On Windows you need to use `Anaconda3 `__ - or `Miniconda3 `__ to install all the - dependencies. + On Windows you need to use `Anaconda3 `__ + or `Miniconda3 `__ to install all the + dependencies. - 3. Install compiler requirements. + 3. Install compiler requirements. - .. code:: sh + .. code:: sh - conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime + conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime - 4. Install binary and build dependencies. + 4. Install binary and build dependencies. - .. code:: sh + .. code:: sh - conda install --update-deps -c conda-forge -y openblas cmake + conda install --update-deps -c conda-forge -y openblas cmake 5. Build and install qiskit-aer directly diff --git a/docs/getting_started.rst b/docs/getting_started.rst index e618bad3f282..0dad4e2860a3 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -7,509 +7,512 @@ Getting started Installation ============ -.. tabbed:: Start locally +.. tab-set:: - Qiskit supports Python 3.7 or later. However, both Python and Qiskit are - evolving ecosystems, and sometimes when new releases occur in one or the other, - there can be problems with compatibility. + .. tab-item:: Start locally - We recommend installing `Anaconda `__, a - cross-platform Python distribution for scientific computing. Jupyter, - included in Anaconda, is recommended for interacting with Qiskit. + Qiskit supports Python 3.7 or later. However, both Python and Qiskit are + evolving ecosystems, and sometimes when new releases occur in one or the other, + there can be problems with compatibility. - We recommend using Python virtual environments to cleanly separate Qiskit from - other applications and improve your experience. + We recommend installing `Anaconda `__, a + cross-platform Python distribution for scientific computing. Jupyter, + included in Anaconda, is recommended for interacting with Qiskit. - The simplest way to use environments is by using the ``conda`` command, - included with Anaconda. A Conda environment allows you to specify a specific - version of Python and set of libraries. Open a terminal window in the directory - where you want to work. + We recommend using Python virtual environments to cleanly separate Qiskit from + other applications and improve your experience. - It is preferred that you use the Anaconda prompt installed with Anaconda. - All you have to do is create a virtual environment inside Anaconda and activate the environment. - These commands can be run in the Anaconda prompt irrespective of Windows or Linux machine. + The simplest way to use environments is by using the ``conda`` command, + included with Anaconda. A Conda environment allows you to specify a specific + version of Python and set of libraries. Open a terminal window in the directory + where you want to work. - Create a minimal environment with only Python installed in it. + It is preferred that you use the Anaconda prompt installed with Anaconda. + All you have to do is create a virtual environment inside Anaconda and activate the environment. + These commands can be run in the Anaconda prompt irrespective of Windows or Linux machine. - .. code:: sh + Create a minimal environment with only Python installed in it. - conda create -n ENV_NAME python=3 + .. code:: sh - Activate your new environment. + conda create -n ENV_NAME python=3 - .. code:: sh + Activate your new environment. - conda activate ENV_NAME + .. code:: sh + conda activate ENV_NAME - Next, install the Qiskit package. - .. code:: sh + Next, install the Qiskit package. - pip install qiskit + .. code:: sh - If the packages were installed correctly, you can run ``conda list`` to see the active - packages in your virtual environment. + pip install qiskit - If you intend to use visualization functionality or Jupyter notebooks it is - recommended to install Qiskit with the extra ``visualization`` support: + If the packages were installed correctly, you can run ``conda list`` to see the active + packages in your virtual environment. - .. code:: sh + If you intend to use visualization functionality or Jupyter notebooks it is + recommended to install Qiskit with the extra ``visualization`` support: - pip install qiskit[visualization] + .. code:: sh - It is worth pointing out that if you're a zsh user (which is the default shell on newer - versions of macOS), you'll need to put ``qiskit[visualization]`` in quotes: + pip install qiskit[visualization] - .. code:: sh + It is worth pointing out that if you're a zsh user (which is the default shell on newer + versions of macOS), you'll need to put ``qiskit[visualization]`` in quotes: - pip install 'qiskit[visualization]' + .. code:: sh + pip install 'qiskit[visualization]' -.. tabbed:: Start on the cloud + .. tab-item:: Start on the cloud - The following cloud vendors have Qiskit pre-installed in their environments: + The following cloud vendors have Qiskit pre-installed in their environments: - .. raw:: html + .. raw:: html -
-
-
-
-
+
+
+
+
+
+ + .. customcarditem:: + :header: IBM Quantum Lab + :card_description: Build quantum applications and experiments with Qiskit in a cloud programming environment. + :image: _static/ibm_qlab.png + :link: https://quantum-computing.ibm.com/ - .. customcarditem:: - :header: IBM Quantum Lab - :card_description: Build quantum applications and experiments with Qiskit in a cloud programming environment. - :image: _static/ibm_qlab.png - :link: https://quantum-computing.ibm.com/ + .. customcarditem:: + :header: Strangeworks + :card_description: A platform that enables users and organizations to easily apply quantum computing to their most pressing problems and research. + :image: _static/strangeworks.png + :link: https://strangeworks.com/ - .. customcarditem:: - :header: Strangeworks - :card_description: A platform that enables users and organizations to easily apply quantum computing to their most pressing problems and research. - :image: _static/strangeworks.png - :link: https://strangeworks.com/ + .. raw:: html - .. raw:: html +
+ +
+
+
-
- -
-
-
+ .. tab-item:: Install from source -.. tabbed:: Install from source + Installing the elements from source allows you to access the most recently + updated version of Qiskit 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 code more efficiently. - Installing the elements from source allows you to access the most recently - updated version of Qiskit 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 code more efficiently. + When installing the elements and components from source, by default their + ``development`` version (which corresponds to the ``master`` git branch) will + be used, as opposed to the ``stable`` version (which contains the same codebase + as the published ``pip`` packages). Since the ``development`` versions of an + element or component usually include new features and changes, they generally + require using the ``development`` version of the rest of the items as well. - When installing the elements and components from source, by default their - ``development`` version (which corresponds to the ``master`` git branch) will - be used, as opposed to the ``stable`` version (which contains the same codebase - as the published ``pip`` packages). Since the ``development`` versions of an - element or component usually include new features and changes, they generally - require using the ``development`` version of the rest of the items as well. + .. note:: - .. note:: + The Terra and Aer packages both require a compiler to build from source before + you can install. Ignis, Aqua, and the IBM Quantum Provider backend + do not require a compiler. - The Terra and Aer packages both require a compiler to build from source before - you can install. Ignis, Aqua, and the IBM Quantum Provider backend - do not require a compiler. + Installing elements from source requires the following order of installation to + prevent installing versions of elements that may be lower than those desired if the + ``pip`` version is behind the source versions: - Installing elements from source requires the following order of installation to - prevent installing versions of elements that may be lower than those desired if the - ``pip`` version is behind the source versions: + #. :ref:`qiskit-terra ` + #. :ref:`qiskit-aer ` + #. :ref:`qiskit-ibmq-provider ` + (if you want to connect to the IBM Quantum devices or online + simulator) - #. :ref:`qiskit-terra ` - #. :ref:`qiskit-aer ` - #. :ref:`qiskit-ibmq-provider ` - (if you want to connect to the IBM Quantum devices or online - simulator) + To work with several components and elements simultaneously, use the following + steps for each element. - To work with several components and elements simultaneously, use the following - steps for each element. + .. note:: - .. note:: + Due to the use of namespace packaging in Python, care must be taken in how you + install packages. If you're planning to install any element from source, do not + use the ``qiskit`` meta-package. Also, follow this guide and use a separate virtual + environment for development. If you do choose to mix an existing installation + with your development, refer to + https://github.com/pypa/sample-namespace-packages/blob/master/table.md + for the set of combinations of installation methods that work together. - Due to the use of namespace packaging in Python, care must be taken in how you - install packages. If you're planning to install any element from source, do not - use the ``qiskit`` meta-package. Also, follow this guide and use a separate virtual - environment for development. If you do choose to mix an existing installation - with your development, refer to - https://github.com/pypa/sample-namespace-packages/blob/master/table.md - for the set of combinations of installation methods that work together. + .. raw:: html - .. raw:: html +

Set up the Virtual Development Environment

-

Set up the Virtual Development Environment

+ .. code-block:: sh - .. code-block:: sh + conda create -y -n QiskitDevenv python=3 + conda activate QiskitDevenv - conda create -y -n QiskitDevenv python=3 - conda activate QiskitDevenv + .. _install-qiskit-terra: - .. _install-qiskit-terra: + .. raw:: html - .. raw:: html +

Installing Terra from Source

-

Installing Terra from Source

+ Installing from source requires that you have a C++ compiler on your system that supports + C++11. - Installing from source requires that you have a C++ compiler on your system that supports - C++11. + .. tab-set:: - .. tabbed:: Compiler for Linux + .. tab-item:: Compiler for Linux - On most Linux platforms, the necessary GCC compiler is already installed. + On most Linux platforms, the necessary GCC compiler is already installed. - .. tabbed:: Compiler for macOS + .. tab-item:: Compiler for macOS - If you use macOS, you can install the Clang compiler by installing XCode. - Check if you have XCode and Clang installed by opening a terminal window and entering the - following. + If you use macOS, you can install the Clang compiler by installing XCode. + Check if you have XCode and Clang installed by opening a terminal window and entering the + following. - .. code:: sh + .. code:: sh - clang --version + clang --version - Install XCode and Clang by using the following command. + Install XCode and Clang by using the following command. - .. code:: sh + .. code:: sh - xcode-select --install + xcode-select --install - .. tabbed:: Compiler for Windows + .. tab-item:: Compiler for Windows - On Windows, it is easiest to install the Visual C++ compiler from the - `Build Tools for Visual Studio 2019 `__. - You can instead install Visual Studio version 2015 or 2017, making sure to select the - options for installing the C++ compiler. + On Windows, it is easiest to install the Visual C++ compiler from the + `Build Tools for Visual Studio 2019 `__. + You can instead install Visual Studio version 2015 or 2017, making sure to select the + options for installing the C++ compiler. - Once the compilers are installed, you are ready to install Qiskit Terra. + Once the compilers are installed, you are ready to install Qiskit Terra. - 1. Clone the Terra repository. + 1. Clone the Terra repository. - .. code:: sh + .. code:: sh - git clone https://github.com/Qiskit/qiskit-terra.git + git clone https://github.com/Qiskit/qiskit-terra.git - 2. Cloning the repository creates a local folder called ``qiskit-terra``. + 2. Cloning the repository creates a local folder called ``qiskit-terra``. - .. code:: sh + .. code:: sh - cd qiskit-terra + cd qiskit-terra - 3. Install the Python requirements libraries from your ``qiskit-terra`` directory. + 3. Install the Python requirements libraries from your ``qiskit-terra`` directory. - .. code:: sh + .. code:: sh - pip install cython + pip install cython - 4. If you want to run tests or linting checks, install the developer requirements. + 4. If you want to run tests or linting checks, install the developer requirements. - .. code:: sh + .. code:: sh - pip install -r requirements-dev.txt + pip install -r requirements-dev.txt - 5. Install ``qiskit-terra``. + 5. Install ``qiskit-terra``. - .. code:: sh + .. code:: sh - pip install . + pip install . - If you want to install it in editable mode, meaning that code changes to the - project don't require a reinstall to be applied, you can do this with: + If you want to install it in editable mode, meaning that code changes to the + project don't require a reinstall to be applied, you can do this with: - .. code:: sh + .. code:: sh - pip install -e . + pip install -e . - You can then run the code examples after installing Terra. You can - run the example with the following command. + You can then run the code examples after installing Terra. You can + run the example with the following command. - .. code:: sh + .. code:: sh - python examples/python/using_qiskit_terra_level_0.py + python examples/python/using_qiskit_terra_level_0.py - .. note:: + .. note:: - If you do not intend to install any other components, qiskit-terra will - emit a ``RuntimeWarning`` warning that both qiskit-aer and - qiskit-ibmq-provider are not installed. This is done because - users commonly intend to use the additional elements, - but do not realize they are not installed, or that the installation - of either Aer or the IBM Quantum Provider failed for some reason. If you wish - to suppress these warnings, add:: + If you do not intend to install any other components, qiskit-terra will + emit a ``RuntimeWarning`` warning that both qiskit-aer and + qiskit-ibmq-provider are not installed. This is done because + users commonly intend to use the additional elements, + but do not realize they are not installed, or that the installation + of either Aer or the IBM Quantum Provider failed for some reason. If you wish + to suppress these warnings, add:: - import warnings - warnings.filterwarnings('ignore', category=RuntimeWarning, - module='qiskit') + import warnings + warnings.filterwarnings('ignore', category=RuntimeWarning, + module='qiskit') - before any ``qiskit`` imports in your code. This will suppress the - warning about the missing qiskit-aer and qiskit-ibmq-provider, but - will continue to display any other warnings from qiskit or other packages. + before any ``qiskit`` imports in your code. This will suppress the + warning about the missing qiskit-aer and qiskit-ibmq-provider, but + will continue to display any other warnings from qiskit or other packages. - .. _install-qiskit-aer: + .. _install-qiskit-aer: - .. raw:: html + .. raw:: html -

Installing Aer from Source

+

Installing Aer from Source

- 1. Clone the Aer repository. + 1. Clone the Aer repository. - .. code:: sh + .. code:: sh - git clone https://github.com/Qiskit/qiskit-aer + git clone https://github.com/Qiskit/qiskit-aer - 2. Install build requirements. + 2. Install build requirements. - .. code:: sh + .. code:: sh - pip install cmake scikit-build cython + pip install cmake scikit-build cython - After this, the steps to install Aer depend on which operating system you are - using. Since Aer is a compiled C++ program with a Python interface, there are - non-Python dependencies for building the Aer binary which can't be installed - universally depending on operating system. + After this, the steps to install Aer depend on which operating system you are + using. Since Aer is a compiled C++ program with a Python interface, there are + non-Python dependencies for building the Aer binary which can't be installed + universally depending on operating system. - .. dropdown:: Linux + .. dropdown:: Linux - 3. Install compiler requirements. + 3. Install compiler requirements. - Building Aer requires a C++ compiler and development headers. + Building Aer requires a C++ compiler and development headers. - If you're using Fedora or an equivalent Linux distribution, - install using: + If you're using Fedora or an equivalent Linux distribution, + install using: - .. code:: sh + .. code:: sh - dnf install @development-tools + dnf install @development-tools - For Ubuntu/Debian install it using: + For Ubuntu/Debian install it using: - .. code:: sh + .. code:: sh - apt-get install build-essential + apt-get install build-essential - 4. Install OpenBLAS development headers. + 4. Install OpenBLAS development headers. - If you're using Fedora or an equivalent Linux distribution, - install using: + If you're using Fedora or an equivalent Linux distribution, + install using: - .. code:: sh + .. code:: sh - dnf install openblas-devel + dnf install openblas-devel - For Ubuntu/Debian install it using: + For Ubuntu/Debian install it using: - .. code:: sh + .. code:: sh - apt-get install libopenblas-dev + apt-get install libopenblas-dev - .. dropdown:: macOS + .. dropdown:: macOS - 3. Install dependencies. + 3. Install dependencies. - To use the `Clang `__ compiler on macOS, you need to install - an extra library for supporting `OpenMP `__. You can use `brew `__ - to install this and other dependencies. + To use the `Clang `__ compiler on macOS, you need to install + an extra library for supporting `OpenMP `__. You can use `brew `__ + to install this and other dependencies. - .. code:: sh + .. code:: sh - brew install libomp + brew install libomp - 4. Then install a BLAS implementation; `OpenBLAS `__ - is the default choice. + 4. Then install a BLAS implementation; `OpenBLAS `__ + is the default choice. - .. code:: sh + .. code:: sh - brew install openblas + brew install openblas - Next, install ``Xcode Command Line Tools``. + Next, install ``Xcode Command Line Tools``. - .. code:: sh + .. code:: sh - xcode-select --install + xcode-select --install - .. dropdown:: Windows + .. dropdown:: Windows - On Windows you need to use `Anaconda3 `__ - or `Miniconda3 `__ to install all the - dependencies. + On Windows you need to use `Anaconda3 `__ + or `Miniconda3 `__ to install all the + dependencies. - 3. Install compiler requirements. + 3. Install compiler requirements. - .. code:: sh + .. code:: sh - conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime + conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime - Qiskit Aer is a high performance simulator framework for quantum circuits. It - provides `several backends `__ - to achieve different simulation goals. + Qiskit Aer is a high performance simulator framework for quantum circuits. It + provides `several backends `__ + to achieve different simulation goals. - .. code:: sh + .. code:: sh - conda install --update-deps -c conda-forge -y openblas cmake + conda install --update-deps -c conda-forge -y openblas cmake - 5. Build and install qiskit-aer directly + 5. Build and install qiskit-aer directly - If you have pip <19.0.0 installed and your environment doesn't require a - custom build, run: + If you have pip <19.0.0 installed and your environment doesn't require a + custom build, run: - .. code:: sh + .. code:: sh - cd qiskit-aer - pip install . + cd qiskit-aer + pip install . - This will both build the binaries and install Aer. + This will both build the binaries and install Aer. - Alternatively, if you have a newer pip installed, or have some custom requirement, - you can build a Python wheel manually. + Alternatively, if you have a newer pip installed, or have some custom requirement, + you can build a Python wheel manually. - .. code:: sh + .. code:: sh - cd qiskit-aer - python ./setup.py bdist_wheel + cd qiskit-aer + python ./setup.py bdist_wheel - If you need to set a custom option during the wheel build, refer to - :ref:`aer_wheel_build_options`. + If you need to set a custom option during the wheel build, refer to + :ref:`aer_wheel_build_options`. - After you build the Python wheel, it will be stored in the ``dist/`` dir in the - Aer repository. The exact version will depend + After you build the Python wheel, it will be stored in the ``dist/`` dir in the + Aer repository. The exact version will depend - .. code:: sh + .. code:: sh - cd dist - pip install qiskit_aer-*.whl + cd dist + pip install qiskit_aer-*.whl - The exact filename of the output wheel file depends on the current version of - Aer under development. + The exact filename of the output wheel file depends on the current version of + Aer under development. - .. _aer_wheel_build_options: + .. _aer_wheel_build_options: - .. raw:: html + .. raw:: html -

Custom options

+

Custom options

- The Aer build system uses `scikit-build `__ - to run the compilation when building it with the Python interface. It acts as an interface for - `setuptools `__ to call `CMake `__ - and compile the binaries for your local system. + The Aer build system uses `scikit-build `__ + to run the compilation when building it with the Python interface. It acts as an interface for + `setuptools `__ to call `CMake `__ + and compile the binaries for your local system. - Due to the complexity of compiling the binaries, you may need to pass options - to a certain part of the build process. The way to pass variables is: + Due to the complexity of compiling the binaries, you may need to pass options + to a certain part of the build process. The way to pass variables is: - .. code:: sh + .. code:: sh - python setup.py bdist_wheel [skbuild_opts] [-- [cmake_opts] [-- build_tool_opts]] + python setup.py bdist_wheel [skbuild_opts] [-- [cmake_opts] [-- build_tool_opts]] - where the elements within square brackets `[]` are optional, and - ``skbuild_opts``, ``cmake_opts``, ``build_tool_opts`` are to be replaced by - flags of your choice. A list of *CMake* options is available here: - https://cmake.org/cmake/help/v3.6/manual/cmake.1.html#options. For - example, you could run something like: + where the elements within square brackets `[]` are optional, and + ``skbuild_opts``, ``cmake_opts``, ``build_tool_opts`` are to be replaced by + flags of your choice. A list of *CMake* options is available here: + https://cmake.org/cmake/help/v3.6/manual/cmake.1.html#options. For + example, you could run something like: - .. code:: sh + .. code:: sh - python setup.py bdist_wheel -- -- -j8 + python setup.py bdist_wheel -- -- -j8 - This is passing the flag `-j8` to the underlying build system (which in this - case is `Automake `__), telling it that you want - to build in parallel using 8 processes. + This is passing the flag `-j8` to the underlying build system (which in this + case is `Automake `__), telling it that you want + to build in parallel using 8 processes. - For example, a common use case for these flags on linux is to specify a - specific version of the C++ compiler to use (normally if the default is too - old): + For example, a common use case for these flags on linux is to specify a + specific version of the C++ compiler to use (normally if the default is too + old): - .. code:: sh + .. code:: sh - python setup.py bdist_wheel -- -DCMAKE_CXX_COMPILER=g++-7 + python setup.py bdist_wheel -- -DCMAKE_CXX_COMPILER=g++-7 - which will tell CMake to use the g++-7 command instead of the default g++ when - compiling Aer. + which will tell CMake to use the g++-7 command instead of the default g++ when + compiling Aer. - Another common use case for this, depending on your environment, is that you may - need to specify your platform name and turn off static linking. + Another common use case for this, depending on your environment, is that you may + need to specify your platform name and turn off static linking. - .. code:: sh + .. code:: sh - python setup.py bdist_wheel --plat-name macosx-10.9-x86_64 \ - -- -DSTATIC_LINKING=False -- -j8 + python setup.py bdist_wheel --plat-name macosx-10.9-x86_64 \ + -- -DSTATIC_LINKING=False -- -j8 - Here ``--plat-name`` is a flag to setuptools, to specify the platform name to - use in the package metadata, ``-DSTATIC_LINKING`` is a flag for using CMake - to disable static linking, and ``-j8`` is a flag for using Automake to use - 8 processes for compilation. + Here ``--plat-name`` is a flag to setuptools, to specify the platform name to + use in the package metadata, ``-DSTATIC_LINKING`` is a flag for using CMake + to disable static linking, and ``-j8`` is a flag for using Automake to use + 8 processes for compilation. - A list of common options depending on platform are: + A list of common options depending on platform are: - +--------+------------+----------------------+---------------------------------------------+ - |Platform| Tool | Option | Use Case | - +========+============+======================+=============================================+ - | All | Automake | -j | Followed by a number, sets the number of | - | | | | processes to use for compilation. | - +--------+------------+----------------------+---------------------------------------------+ - | Linux | CMake | -DCMAKE_CXX_COMPILER | Used to specify a specific C++ compiler; | - | | | | this is often needed if your default g++ is | - | | | | too old. | - +--------+------------+----------------------+---------------------------------------------+ - | OSX | setuptools | --plat-name | Used to specify the platform name in the | - | | | | output Python package. | - +--------+------------+----------------------+---------------------------------------------+ - | OSX | CMake | -DSTATIC_LINKING | Used to specify whether or not | - | | | | static linking should be used. | - +--------+------------+----------------------+---------------------------------------------+ + +--------+------------+----------------------+---------------------------------------------+ + |Platform| Tool | Option | Use Case | + +========+============+======================+=============================================+ + | All | Automake | -j | Followed by a number, sets the number of | + | | | | processes to use for compilation. | + +--------+------------+----------------------+---------------------------------------------+ + | Linux | CMake | -DCMAKE_CXX_COMPILER | Used to specify a specific C++ compiler; | + | | | | this is often needed if your default g++ is | + | | | | too old. | + +--------+------------+----------------------+---------------------------------------------+ + | OSX | setuptools | --plat-name | Used to specify the platform name in the | + | | | | output Python package. | + +--------+------------+----------------------+---------------------------------------------+ + | OSX | CMake | -DSTATIC_LINKING | Used to specify whether or not | + | | | | static linking should be used. | + +--------+------------+----------------------+---------------------------------------------+ - .. note:: - Some of these options are not platform-specific. These particular platforms are listed - because they are commonly used in the environment. Refer to the - tool documentation for more information. + .. note:: + Some of these options are not platform-specific. These particular platforms are listed + because they are commonly used in the environment. Refer to the + tool documentation for more information. - .. _install-qiskit-ibmq-provider: + .. _install-qiskit-ibmq-provider: - .. raw:: html + .. raw:: html -

Installing IBM Quantum Provider from Source

+

Installing IBM Quantum Provider from Source

- 1. Clone the qiskit-ibmq-provider repository. + 1. Clone the qiskit-ibmq-provider repository. - .. code:: sh + .. code:: sh - git clone https://github.com/Qiskit/qiskit-ibmq-provider.git + git clone https://github.com/Qiskit/qiskit-ibmq-provider.git - 2. Cloning the repository creates a local directory called ``qiskit-ibmq-provider``. + 2. Cloning the repository creates a local directory called ``qiskit-ibmq-provider``. - .. code:: sh + .. code:: sh - cd qiskit-ibmq-provider + cd qiskit-ibmq-provider - 3. If you want to run tests or linting checks, install the developer requirements. - This is not required to install or use the qiskit-ibmq-provider package when - installing from source. + 3. If you want to run tests or linting checks, install the developer requirements. + This is not required to install or use the qiskit-ibmq-provider package when + installing from source. - .. code:: sh + .. code:: sh - pip install -r requirements-dev.txt + pip install -r requirements-dev.txt - 4. Install qiskit-ibmq-provider. + 4. Install qiskit-ibmq-provider. - .. code:: sh + .. code:: sh - pip install . + pip install . - If you want to install it in editable mode, meaning that code changes to the - project don't require a reinstall to be applied: + If you want to install it in editable mode, meaning that code changes to the + project don't require a reinstall to be applied: - .. code:: sh + .. code:: sh - pip install -e . + pip install -e . Platform Support ----------------