From 674b58a55970cea982f9bb1a7d50b94c334922f1 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 16 Jul 2024 14:32:21 -0500 Subject: [PATCH 1/7] Add more details --- docs/guides/install-qiskit.mdx | 47 ++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index 0d02e9a5af7..e73f3bcd94a 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -13,11 +13,11 @@ Whether you will work locally or in a cloud environment, the first step for all (If you are installing Qiskit for the first time, skip ahead to the [Install and set up](#local) section. This notice is relevant only to users who have installed Qiskit previously.) - **For those upgrading from version 0.x to 1.0 or later**: note that because Qiskit 1.0 uses a new packaging structure, you **cannot** use `pip install -U qiskit` to upgrade from any Qiskit 0.x version to 1.0. - - See the [Qiskit 1.0 migration guide](/api/migration-guides/qiskit-1.0) for details and instructions. - - Future updates starting with Qiskit 1.0 will allow for in-place upgrades. + **For those upgrading from version 0.x to 1.0 or later**: note that because Qiskit 1.0 uses a new packaging structure, you **cannot** use `pip install -U qiskit` to upgrade from any Qiskit 0.x version to 1.0. + + See the [Qiskit 1.0 migration guide](/api/migration-guides/qiskit-1.0) for details and instructions. + + Future updates starting with Qiskit 1.0 will allow for in-place upgrades. @@ -26,7 +26,11 @@ Whether you will work locally or in a cloud environment, the first step for all 1. Install Python. Check the "Programming Language" section on the [Qiskit PyPI project page](https://pypi.org/project/qiskit/) to determine which Python versions are supported by the most recent release. For download instructions, see the [Python Beginners Guide.](https://wiki.python.org/moin/BeginnersGuide/Download) - We recommend that you use [Python virtual environments](https://docs.python.org/3.10/tutorial/venv.html) to separate Qiskit from other applications. + It is recommended that you use [Python virtual environments](https://docs.python.org/3.10/tutorial/venv.html) to separate Qiskit from other applications. + + + These instructions use Python installed directly from pypi.org, however, you can use other Python environments, such as [Anaconda](https://docs.anaconda.com/anaconda/) or [miniconda](https://docs.anaconda.com/miniconda/). +
@@ -35,11 +39,11 @@ Whether you will work locally or in a cloud environment, the first step for all A virtual Python environment is an isolated space to work with Python for a specific purpose — so you can install whatever packages you wish, and set up libraries, dependencies, and so on, without affecting the "base" Python environment on your machine. One important advantage of a virtual environment is that if your Python environment becomes corrupted somewhere along the way, you can easily delete the virtual environment and start over! - - Choose a preferred location in which to store information about your virtual environments. Commonly they're stored in a directory named `.venv` within a user's home directory. + + Choose a preferred location in which to store information about your virtual environments. Commonly they're stored in a directory named `.venv` within a user's home directory.
- First, create a minimal environment with only Python installed in it. + First, create a minimal environment with only Python installed in it. @@ -83,10 +87,13 @@ Whether you will work locally or in a cloud environment, the first step for all -1. [Install pip](https://pip.pypa.io/en/stable/installation/). Pip is a Python package manager that you use to install Qiskit and other Python packages. Use `pip list` to see what is in your virtual environment. +1. [Install pip](https://pip.pypa.io/en/stable/installation/) if you don't use a Python environment. Pip is a Python package manager that you use to install Qiskit and other Python packages. Use `pip list` to see what is in your virtual environment. If you use a Python environment, it's already installed in the environment. 1. Install the Qiskit SDK. If you plan to run jobs on quantum hardware, also install Qiskit Runtime. - +
+ + Click here for instructions. + ```shell pip install qiskit ``` @@ -112,6 +119,8 @@ Whether you will work locally or in a cloud environment, the first step for all +
+ 1. If you want to run a Jupyter notebook with the Qiskit packages you just installed, you will need to install Jupyter in your environment. ```shell @@ -238,7 +247,7 @@ period between major version releases is one year. Minor versions introduce new features and bug fixes without breaking API compatibility, and are periodically (currently every three months) published for **only** the current major version. Patch versions provide fixes for bugs identified in -the most recent minor version of each actively supported release series (that is, the +the most recent minor version of each actively supported release series (that is, the major version). We support at most two release series at a time, which occurs only during the period of overlap following a new major version release, described in more detail below. @@ -257,13 +266,13 @@ For an up-to-date release schedule, refer to the Qiskit Github project's [milest With the release of a new major version, the previous major version is supported for at least six months; only bug and security fixes are accepted during this time and only patch releases are published for this major version. A final -patch version is published when support is dropped, and that release +patch version is published when support is dropped, and that release also documents the end of support for that major version series. A longer support window is needed for the previous major version as this gives downstream Qiskit consumers and their users a chance to migrate their code. -Downstream libraries that +Downstream libraries that depend on Qiskit should not raise their minimum required Qiskit version to a new -major version immediately after its release because the library's user base needs time +major version immediately after its release because the library's user base needs time to migrate to the new API changes. Having an extended support window for the previous major Qiskit version gives downstream projects time to ensure compatibility with the next major version. Downstream projects can provide @@ -322,15 +331,15 @@ For example, specifying `qiskit<2` in a requirements file when the current major Qiskit version is 1 ensures that you're using a version of Qiskit that doesn't have breaking API changes. -Capping the version less than the next major version +Capping the version less than the next major version ensures that you see any deprecation warnings before a -major version release. -Without the cap, `pip` installs +major version release. +Without the cap, `pip` installs the newest version available by default. The QPY serialization format is backwards-compatible so that a new Qiskit release can always load a QPY file generated with an earlier release of Qiskit. However, the format isn't forward-compatible so, in principle, it's not possible -to load QPY files generated with a newer version of Qiskit using an older release. To facilitate user migration across major version releases, the (`qiskit.qpy.dump()`](/api/qiskit/qpy#dump) function will always support at least one overlapping version between the `X.0.0` and the `X-1.Y.0` release (where `Y` is the last minor version of +to load QPY files generated with a newer version of Qiskit using an older release. To facilitate user migration across major version releases, the (`qiskit.qpy.dump()`](/api/qiskit/qpy#dump) function will always support at least one overlapping version between the `X.0.0` and the `X-1.Y.0` release (where `Y` is the last minor version of that series). The parameter `qiskit.qpy.dump(..., version=...)` will enable saving QPY format files that can be loaded by both major versions from the newer release. See more details in [RFC 0020](https://github.com/Qiskit/RFCs/blob/master/0020-release_cycle.md#qpy-support). From 418526f6f14d2978aa960a2acc880f55b56ee855 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 16 Jul 2024 14:58:03 -0500 Subject: [PATCH 2/7] Add note --- docs/guides/install-qiskit.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index e73f3bcd94a..55cd4fb10be 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -29,7 +29,7 @@ Whether you will work locally or in a cloud environment, the first step for all It is recommended that you use [Python virtual environments](https://docs.python.org/3.10/tutorial/venv.html) to separate Qiskit from other applications. - These instructions use Python installed directly from pypi.org, however, you can use other Python environments, such as [Anaconda](https://docs.anaconda.com/anaconda/) or [miniconda](https://docs.anaconda.com/miniconda/). + These instructions use Python installed directly from pypi.org. However, you can use other Python environments, such as [Anaconda](https://docs.anaconda.com/anaconda/) or [miniconda](https://docs.anaconda.com/miniconda/).
@@ -90,10 +90,7 @@ Whether you will work locally or in a cloud environment, the first step for all 1. [Install pip](https://pip.pypa.io/en/stable/installation/) if you don't use a Python environment. Pip is a Python package manager that you use to install Qiskit and other Python packages. Use `pip list` to see what is in your virtual environment. If you use a Python environment, it's already installed in the environment. 1. Install the Qiskit SDK. If you plan to run jobs on quantum hardware, also install Qiskit Runtime. -
- - Click here for instructions. - + ```shell pip install qiskit ``` @@ -119,7 +116,6 @@ Whether you will work locally or in a cloud environment, the first step for all -
1. If you want to run a Jupyter notebook with the Qiskit packages you just installed, you will need to install Jupyter in your environment. @@ -135,7 +131,7 @@ Whether you will work locally or in a cloud environment, the first step for all If you are planning to work locally and use simulators built into Qiskit, then your installation is done. If you want to run jobs on IBM Quantum systems, next [select an access channel](setup-channel) and finish your setup. - Periodically check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) to see new releases. We recommend frequently updating your requirements for `qiskit` and `qiskit-ibm-runtime` by, for example, changing the versions in `requirements.txt` to the latest versions. + Periodically check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) to see new releases, then run `pip install --upgrade ` when a new version is released. We recommend frequently updating your requirements for `qiskit` and `qiskit-ibm-runtime` by, for example, changing the versions in `requirements.txt` to the latest versions. ## Troubleshooting From 05b8e2e69fd44d428997b6bde5df551aaa41a92e Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 16 Jul 2024 16:03:39 -0500 Subject: [PATCH 3/7] edits --- docs/guides/install-qiskit.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index 55cd4fb10be..4670a8b82f6 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -87,7 +87,7 @@ Whether you will work locally or in a cloud environment, the first step for all -1. [Install pip](https://pip.pypa.io/en/stable/installation/) if you don't use a Python environment. Pip is a Python package manager that you use to install Qiskit and other Python packages. Use `pip list` to see what is in your virtual environment. If you use a Python environment, it's already installed in the environment. +1. [Install pip](https://pip.pypa.io/en/stable/installation/) if you don't use a Python environment. Pip is a Python package manager that you use to install Qiskit and other Python packages. Use `pip list` to see what is in your virtual environment. If you use a Python environment, pip is already installed in the environment. 1. Install the Qiskit SDK. If you plan to run jobs on quantum hardware, also install Qiskit Runtime. @@ -131,7 +131,7 @@ Whether you will work locally or in a cloud environment, the first step for all If you are planning to work locally and use simulators built into Qiskit, then your installation is done. If you want to run jobs on IBM Quantum systems, next [select an access channel](setup-channel) and finish your setup. - Periodically check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) to see new releases, then run `pip install --upgrade ` when a new version is released. We recommend frequently updating your requirements for `qiskit` and `qiskit-ibm-runtime` by, for example, changing the versions in `requirements.txt` to the latest versions. + Periodically check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) to see new releases, then run `pip install --upgrade ` to upgrade to thew new version. We recommend frequently updating your requirements for `qiskit` and `qiskit-ibm-runtime` by, for example, changing the versions in `requirements.txt` to the latest versions. ## Troubleshooting From e472032920f87436f2e1ee760dd8c1911a124fe8 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 17 Jul 2024 09:41:39 -0500 Subject: [PATCH 4/7] comments from Eric --- docs/guides/install-qiskit.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index 4670a8b82f6..b1cbd54a3da 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -29,7 +29,7 @@ Whether you will work locally or in a cloud environment, the first step for all It is recommended that you use [Python virtual environments](https://docs.python.org/3.10/tutorial/venv.html) to separate Qiskit from other applications. - These instructions use Python installed directly from pypi.org. However, you can use other Python environments, such as [Anaconda](https://docs.anaconda.com/anaconda/) or [miniconda](https://docs.anaconda.com/miniconda/). + These instructions use the standard Python distribution from pypi.org. However, you can use other Python distributions, such as [Anaconda](https://docs.anaconda.com/anaconda/) or [miniconda](https://docs.anaconda.com/miniconda/), along with other dependency management workflows like [Poetry](https://python-poetry.org/docs/).
@@ -87,7 +87,7 @@ Whether you will work locally or in a cloud environment, the first step for all -1. [Install pip](https://pip.pypa.io/en/stable/installation/) if you don't use a Python environment. Pip is a Python package manager that you use to install Qiskit and other Python packages. Use `pip list` to see what is in your virtual environment. If you use a Python environment, pip is already installed in the environment. +1. [Install pip](https://pip.pypa.io/en/stable/installation/) if it's not already installed in your environment. Pip is a Python package manager that you use to install Qiskit and other Python packages. Use `pip list` to see what is in your virtual environment. In most Python environments, pip is already installed. 1. Install the Qiskit SDK. If you plan to run jobs on quantum hardware, also install Qiskit Runtime. @@ -131,7 +131,7 @@ Whether you will work locally or in a cloud environment, the first step for all If you are planning to work locally and use simulators built into Qiskit, then your installation is done. If you want to run jobs on IBM Quantum systems, next [select an access channel](setup-channel) and finish your setup. - Periodically check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) to see new releases, then run `pip install --upgrade ` to upgrade to thew new version. We recommend frequently updating your requirements for `qiskit` and `qiskit-ibm-runtime` by, for example, changing the versions in `requirements.txt` to the latest versions. + Periodically check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) to see new releases, then run `pip install --upgrade ` to upgrade to thew new version. We recommend frequently updating your requirements for `qiskit` and `qiskit-ibm-runtime` by, for example, changing the versions in `requirements.txt` to the latest versions, then running `pip install -r requirements.txt` or the appropriate command for your dependency management workflow. ## Troubleshooting From fc5cf7f07755bdd75ac7839f783258753ef8b9be Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 17 Jul 2024 09:46:25 -0500 Subject: [PATCH 5/7] eric comments --- docs/guides/install-qiskit.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index b1cbd54a3da..83c59c50e46 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -131,7 +131,7 @@ Whether you will work locally or in a cloud environment, the first step for all If you are planning to work locally and use simulators built into Qiskit, then your installation is done. If you want to run jobs on IBM Quantum systems, next [select an access channel](setup-channel) and finish your setup. - Periodically check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) to see new releases, then run `pip install --upgrade ` to upgrade to thew new version. We recommend frequently updating your requirements for `qiskit` and `qiskit-ibm-runtime` by, for example, changing the versions in `requirements.txt` to the latest versions, then running `pip install -r requirements.txt` or the appropriate command for your dependency management workflow. + Periodically check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) to see new releases. We recommend frequently updating your requirements for `qiskit` and `qiskit-ibm-runtime` by, for example, changing the versions in `requirements.txt` to the latest versions, then running `pip install -r requirements.txt` or the appropriate command for your dependency management workflow. ## Troubleshooting From 632ab982f52dde70b433e5674df739bdacb9845a Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 17 Jul 2024 10:00:06 -0500 Subject: [PATCH 6/7] Update docs/guides/install-qiskit.mdx Co-authored-by: abbycross --- docs/guides/install-qiskit.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index 83c59c50e46..7e6f04ddb5f 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -13,7 +13,7 @@ Whether you will work locally or in a cloud environment, the first step for all (If you are installing Qiskit for the first time, skip ahead to the [Install and set up](#local) section. This notice is relevant only to users who have installed Qiskit previously.) - **For those upgrading from version 0.x to 1.0 or later**: note that because Qiskit 1.0 uses a new packaging structure, you **cannot** use `pip install -U qiskit` to upgrade from any Qiskit 0.x version to 1.0. + **For those upgrading from version 0.x to 1.0 or later**: note that because Qiskit v1.0 uses a new packaging structure, you **cannot** use `pip install -U qiskit` to upgrade from any Qiskit 0.x version to 1.0. See the [Qiskit 1.0 migration guide](/api/migration-guides/qiskit-1.0) for details and instructions. From c5da7b11327cb726d5fb3d2e7ea9b6c4852e8720 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 17 Jul 2024 10:11:14 -0500 Subject: [PATCH 7/7] add the link --- docs/guides/install-qiskit.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index 7e6f04ddb5f..bf631006abc 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -29,7 +29,7 @@ Whether you will work locally or in a cloud environment, the first step for all It is recommended that you use [Python virtual environments](https://docs.python.org/3.10/tutorial/venv.html) to separate Qiskit from other applications. - These instructions use the standard Python distribution from pypi.org. However, you can use other Python distributions, such as [Anaconda](https://docs.anaconda.com/anaconda/) or [miniconda](https://docs.anaconda.com/miniconda/), along with other dependency management workflows like [Poetry](https://python-poetry.org/docs/). + These instructions use the standard Python distribution from [pypi.org](https://pypi.org/). However, you can use other Python distributions, such as [Anaconda](https://docs.anaconda.com/anaconda/) or [miniconda](https://docs.anaconda.com/miniconda/), along with other dependency management workflows like [Poetry](https://python-poetry.org/docs/).