Merge branch 'main' into adapt-vqe

CONTRIBUTING.md

@@ -7,7 +7,7 @@
 # Contributing
 __We appreciate all kinds of help, so thank you!__
 
-This guide is for those who want to extend the module or documentation. If you just want to use the package, read [this other guide](./docs/reference_guide.md) instead.
+This guide is for those who want to extend the module or documentation. If you just want to use the software, read [this other guide](./docs/reference_guide.md) instead.
 
 
 ## Table of contents
@@ -43,7 +43,7 @@ Other than submitting new source code, users can contribute in a number of meani
 ## Initial set-up
 
 ### Installing dependencies
-In order to contribute, you will need to [install the module from source](/INSTALL.md#installation-from-source) with developer dependencies (i.e. `dev` bundle) and, optionally, in editable mode. We recommend using the latest version of python available despite the fact that this package maintains support for legacy versions, as some of the developer tools require newer functionality to work (e.g. type annotation format introduced in python 3.10).
+In order to contribute, you will need to [install the module from source](/INSTALL.md#installation-from-source) with developer dependencies (i.e. `dev` bundle) and, optionally, in editable mode. We recommend using the latest version of python available despite the fact that this software maintains support for legacy versions, as some of the developer tools require newer functionality to work (e.g. type annotation format introduced in python 3.10).
 
 If you do not have write permissions to the original repository, you will need to open a fork in your personal account first, and submit all pull requests (PR) from there. Even if you have write permissions, forking the repository should always work provided that this functionality is enabled, so this is the recommended approach.
 

DEPRECATION.md

@@ -9,7 +9,7 @@ To avoid dependency issues, exact version specification is encouraged if no upco
 
 Following [Python's naming conventions](https://realpython.com/python-double-underscore/) as outlined by [PEP8](https://peps.python.org/pep-0008/), any module, variable, function, or class whose name starts with a leading underscore `_` will be considered _internal_ and not part of this library's supported _application programming interface_ (API).
 
-Some capabilities may be pre-released before reaching a stable state. These will not adhere to the deprecation policies in place and will actively warn users of their unstable, pre-release, condition until they are deemed otherwise.
+Some capabilities may be pre-released before reaching a mature, stable state. These will not adhere to the deprecation policies in place and will actively warn users of their _experimental_, unstable state until otherwise deemed.
 
 Every other piece of source code conforms the _public-facing_ API of this library and will therefore be subject to the rules outlined in this document.
 
@@ -25,13 +25,13 @@ Said deprecation process will last for at least three months, and will not begin
 
 This library follows [semantic versioning](https://semver.org/) (i.e. `MAJOR.MINOR.PATCH`).
 
-In most cases, functionality will not be changed or removed without displaying active warnings for a sufficiently long period of time. During this period, we will keep old interfaces and mark them as _deprecated_. Deprecations, changes and removals are considered API modifications, and can only occur in _minor_ releases, not _patch_ releases.
+In most cases, functionality will not be changed or removed without displaying active warnings for a sufficiently long period of time. During this period, we will keep old interfaces and mark them as _deprecated_. Deprecations can only occur in _minor_ releases, not _patch_ releases.
 
-We may occasionally introduce breaking changes (i.e. backwards incompatible) in order to bring new functionality to users more rapidly, simplify existing tooling, or facilitate maintenance. These changes will only be included in _major_ releases.
+We may occasionally introduce breaking changes (i.e. backwards incompatible) in order to bring new functionality to users more rapidly, simplify existing tooling, or facilitate maintenance. These will only occur in _major_ releases, not _minor_ or _patch_ releases. Changes and removals are considered API modifications, and therefore breaking changes. Major version zero (i.e. `0.X.Y`) may include breaking changes in minor releases.
 
-Major version zero (i.e. `0.X.Y`) may include breaking changes in minor releases.
+No support for old versions will be provided.
 
 
 ## Documenting changes
 
-Each substantial improvement, breaking change, or deprecation occurring for each release will be documented in [`CHANGELOG.md`](https://github.com/IBM-Quantum-Technical-Enablement/quantum-enablement/blob/main/CHANGELOG.md).
+Each substantial improvement, breaking change, or deprecation occurring for each release will be documented in [`CHANGELOG.md`](CHANGELOG.md).

FILEMAP.md

@@ -3,7 +3,7 @@
 ## Guidelines
 
 - [`CITATION.bib`](CITATION.bib) --
-  BibTeX file including the bibliographic reference to cite the software package.
+  BibTeX file including the bibliographic reference to cite the software.
 - [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) --
   participation in the repository is subject to these conduct guidelines.
 - [`CONTRIBUTING.md`](CONTRIBUTING.md) --
@@ -13,19 +13,19 @@
 - [`FILEMAP.md`](FILEMAP.md) --
   a summary of the repository structure and explanations of the different files and folders.
 - [`INSTALL.md`](INSTALL.md) --
-  guidelines to install the software package contained in this repo.
+  guidelines to install the software contained in this repo.
 - [`LICENSE.txt`](LICENSE.txt) --
   one of the [standard legal requirements](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository) for an open source project. There are different types of [licenses for software](https://en.wikipedia.org/wiki/Software_license), some of the most popular being [open source](https://opensource.org/licenses).
 - [`README.md`](README.md) -- 
   main readme for repository.
 
 
-## Software package
+## Software package/library
 
 - `<pyproject_qiskit>` -- 
-  it will have a different name for each repository using the [`pyproject-qiskit` template](https://github.com/pedrorrivero/pyproject-qiskit), and it holds the source code for the software package. This name will determine how the package is imported after installation (e.g. `from <pyproject_qiskit> import __version__`).
+  it will have a different name for each repository using the [`pyproject-qiskit` template](https://github.com/pedrorrivero/pyproject-qiskit), and it holds the source code for the software. This name will determine how the software is imported after installation (e.g. `from <pyproject_qiskit> import __version__`).
 - [`CHANGELOG.md`](CHANGELOG.md) --
-  file that logs all the changes made to the software package on each new version release.
+  file that logs all the changes made to the software on each new version release.
 - [`docs`](docs) -- 
   documentation for the repository (e.g. tutorials, API docs, reference guide).
 - [`test`](test) -- 
@@ -95,6 +95,6 @@
 - [`.pylintrc`](.pylintrc) --
   configuration for [Pylint](https://pylint.readthedocs.io/), a tool for static code analysis (e.g. lint errors).
 - [`pytest.ini`](pytest.ini) --
-  configuration for the [PyTest framework](https://pytest.org) used for testing the software package.
+  configuration for the [PyTest framework](https://pytest.org) used for testing the software.
 - [`tox.ini`](tox.ini) -- 
   configuration file for [tox](https://tox.readthedocs.io/en/latest/) framework that aims to automate and standardize testing in Python. Eases the packaging, testing and release process of Python software.

INSTALL.md

@@ -1,15 +1,16 @@
 # Installation Guide
 
-The following installation guide is generic and therefore needs to be adapted to the particular package that you want to install. This is easily done by replacing:
-1. The template _repo url_ `https://github.com/pedrorrivero/pyproject-qiskit.git` with the url of the remote git repository hosting the package (e.g. `https://github.com/Qiskit-Extensions/staged-primitives.git`).
-2. The template _name_ `pyproject-qiskit` with the name of the desired package (e.g. `staged-primitives`).
-3. The template _import name_ `pyproject_qiskit` with the import name of the desired package (e.g. `staged_primitives`).
+> [!IMPORTANT]
+> The following guide is generic and therefore needs to be adapted to the particular software to install. This is easily done by replacing:
+> 1. `<REPO-URL>` with the _URL_ of the remote git repository hosting the software (e.g. `https://github.com/Qiskit-Community/prototype-zne`).
+> 2. `<SOFTWARE-NAME>` with the _name_ of the desired software (e.g. `prototype-zne`).
+> 3. `<IMPORT-NAME>` with the _import name_ of the desired software (e.g. `zne`).
 
-To follow along, make sure that your local environment is compatible with the package:
+To follow along, make sure that your local environment is compatible with the software:
 - Supported operating system (Linux, macOS, or Windows).
 - Supported Python version (3.8 – 3.12).
 - (Optional) We recommend updating `pip` to its latest version:
-    ```
+    ```sh
     pip install -U pip
     ```
 
@@ -25,54 +26,54 @@ To follow along, make sure that your local environment is compatible with the pa
 
 ## Setting up a Python environment
 
-Although not strictly required, it can be useful to create a new *virtual environment* with a custom name (here referred to as `<VENV-NAME>`, common names are `venv` and `.venv`) to avoid dependency conflicts. We recommend using the latest Python version supported by the package. There are several alternatives to do this within the terminal:
+Although not strictly required, it can be useful to create a new *virtual environment* with a custom name (here referred to as `<VENV-NAME>`, common names are `venv` and `.venv`) to avoid dependency conflicts. We recommend using the latest Python version supported by the software. There are several alternatives to do this within the terminal:
 
 - Using `venv` from the [python standard library](https://docs.python.org/3/library/venv.html):
-    ```
+    ```sh
     python -m venv <VENV-NAME>
     source <VENV-NAME>/bin/activate
     ```
     To deactivate and delete the virtual environment afterwards do:
-    ```
+    ```sh
     deactivate
     rm -r <VENV-NAME>
     ```
 - Using `virtualenv` after [installation](https://virtualenv.pypa.io/en/latest/index.html):
-    ```
+    ```sh
     python -m virtualenv <VENV-NAME>
     source <VENV-NAME>/bin/activate
     ```
     To deactivate and delete the virtual environment afterwards do:
-    ```
+    ```sh
     deactivate
     rm -r <VENV-NAME>
     ```
 - Using `conda` after installing [Miniconda](https://docs.conda.io/en/latest/miniconda.html):
-    ```
+    ```sh
     conda create -n <VENV-NAME> python=<PYTHON-VERSION>
     conda activate <VENV-NAME>
     ```
     To deactivate and delete the virtual environment afterwards do:
-    ```
+    ```sh
     conda deactivate
     conda env remove -n <VENV-NAME>
     ```
 
 
 ## Basic PyPI installation
 
-The easiest way to install this package is from the PyPI public repository. This will install the latest stable version available, which will provide a higher level of robustness, although patches and updates might take longer to be available. From the terminal, use `pip` to install the package:
-```
-pip install pyproject-qiskit
+The easiest way to install this software is from the PyPI public repository. This will install the latest stable version available, which will provide a higher level of robustness, although patches and updates might take longer to be available. From the terminal, use `pip` to install the software:
+```sh
+pip install <SOFTWARE-NAME>
 ```
 
-To update the package to its latest release (i.e. at a later point in time):
-```
-pip install -U pyproject-qiskit
+To update the software to its latest release (i.e. at a later point in time):
+```sh
+pip install -U <SOFTWARE-NAME>
 ```
 
 > [!TIP]
-> If this package has not yet been published to PyPI, you will need to [install it from source](#installation-from-source). The easiest way to do so is by installing directly [from the remote git repository](#from-remote) (e.g. GitHub).
+> If this software has not yet been published to PyPI, you will need to [install it from source](#installation-from-source). The easiest way to do so is by installing directly [from the remote git repository](#from-remote) (e.g. GitHub).
 
 
 ## Installation from source
@@ -82,13 +83,13 @@ To get the latest features and patches as soon as they are released, or to contr
 ### From remote
 
 If you don't care about making changes to the source code, you can simply use `pip` to easily install it [from the remote git repository](https://pip.pypa.io/en/stable/topics/vcs-support/):
-```
-pip install pyproject-qiskit@git+https://github.com/pedrorrivero/pyproject-qiskit
+```sh
+pip install <SOFTWARE-NAME>@git+<REPO-URL>
 ```
 
 Updates can be retrieved at any point via:
-```
-pip install -U pyproject-qiskit@git+https://github.com/pedrorrivero/pyproject-qiskit
+```sh
+pip install -U <SOFTWARE-NAME>@git+<REPO-URL>
 ```
 
 ### From local
@@ -97,35 +98,35 @@ If you wish to make changes to the source code, either for [contribution](CONTRI
 
 0. Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed for version control.
 1. From the terminal, clone the repository. This will add the provided URL to the list of remotes under the name `origin`:
-    ```
-    git clone https://github.com/pedrorrivero/pyproject-qiskit.git
+    ```sh
+    git clone <REPO-URL>.git
     ```
     Alternatively, instead of cloning the original repository, you may choose to clone your personal [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) —provided that this functionality is enabled. You can do so by using the appropriate URL and adding the original repository to the list of remotes (here under the name `upstream`). This will be required for [contribution](CONTRIBUTING.md) unless you are granted write permissions for the original repository.
-    ```
-    git clone <YOUR-FORK-URL>
-    git remote add upstream https://github.com/pedrorrivero/pyproject-qiskit.git
+    ```sh
+    git clone <YOUR-FORK-URL>.git
+    git remote add upstream <REPO-URL>.git
     ```
 2. Change directory to the freshly cloned repository:
+    ```sh
+    cd <SOFTWARE-NAME>
     ```
-    cd pyproject-qiskit
-    ```
-3. Install the package and required dependencies:
-    ```
+3. Install the software and required dependencies:
+    ```sh
     pip install .
     ```
-4. (Optional) If you plan to make changes to the code, you can install it in editable mode by passing the `-e` flag to the `pip install` command. This will slightly impact performance, but it will also make sure that you do not need to reinstall the package after every edit for it to work as intended. This is also useful in order to pull new versions and updates from the repository without need to reinstall.
-    ```
+4. (Optional) If you plan to make changes to the code, you can install it in editable mode by passing the `-e` flag to the `pip install` command. This will slightly impact performance, but it will also make sure that you do not need to reinstall the software after every edit for it to work as intended. This is also useful in order to pull new versions and updates from the repository without need to reinstall.
+    ```sh
     pip install -e .
     ```
-5. To update the package to its latest release (i.e. at a later point in time) you will need to pull new changes to the source code from the desired remote repository (e.g. `origin`, `upstream`). From the local directory holding the cloned repository (i.e. use `cd`) run:
-    ```
+5. To update the software to its latest release (i.e. at a later point in time) you will need to pull new changes to the source code from the desired remote repository (e.g. `origin`, `upstream`). From the local directory holding the cloned repository (i.e. use `cd`) run:
+    ```sh
     git pull <REMOTE-REPO> main
     ```
     If you did not install in editable mode, after this, you will also need to reinstall:
+    ```sh
+    pip install -U .
     ```
-    pip install .
-    ```
-    This last command can be skipped by installing the package in editable mode.
+    This last command can be skipped by installing the software in editable mode.
 
 
 ## Optional dependencies
@@ -140,45 +141,47 @@ For developers:
 - `docs` → for documentation (e.g. `sphinx`)
 
 If you wish to install any of these bundles of optional dependencies (e.g. `<OPT-BUN>`) from PyPI use the following format in your installation/update commands:
-```
-pip install [-U] pyproject-qiskit[<OPT-BUN>]
+```sh
+pip install [-U] <SOFTWARE-NAME>[<OPT-BUN>]
 ```
 Or, for multiple optional bundles:
-```
-pip install [-U] pyproject-qiskit[<OPT-BUN-1>,<OPT-BUN-2>]
-```
-If running `zsh` on the terminal (e.g. default shell on macOS devices), you will instead need to enclose the target in between quotation marks:
-```
-pip install [-U] "pyproject-qiskit[<OPT-BUN>]"
-```
-This can be checked by running the following command:
-```
-echo $0
+```sh
+pip install [-U] <SOFTWARE-NAME>[<OPT-BUN-1>,<OPT-BUN-2>]
 ```
 
-The same format can be used for installation of these bundles from source by simply substituting `pyproject-qiskit` for `.` in the install commands. For example:
+The same format can be used for installation of these bundles from _local_ source by simply substituting `<SOFTWARE-NAME>` for `.` in the install commands:
+```sh
+pip install [-U] [-e] .[<OPT-BUN-1>,<OPT-BUN-2>]
 ```
-pip install .[<OPT-BUN-1>,<OPT-BUN-2>]
+Similarly, for installation from _remote_ source:
+```sh
+pip install [-U] <SOFTWARE-NAME>@git+<REPO-URL>[<OPT-BUN-1>,<OPT-BUN-2>]
 ```
 
-Editable mode can also be enabled:
-```
-pip install -e ".[<OPT-BUN-1>,<OPT-BUN-2>]"
-```
+> [!TIP]
+> If running `zsh` on the terminal (e.g. default shell on modern macOS devices), you will instead need to enclose the target in between quotation marks:
+> ```zsh
+> pip install [-U] [-e] "<SOFTWARE-NAME>[<OPT-BUN>]"
+> ```
+> This can be checked by running the following command:
+> ```zsh
+> echo $0
+> ```
+
 
 ## Testing the installation
 
-Users may now run the demo notebooks on their local machine (optional dependencies apply), or use the package in their own software by simply importing it:
+Users may now run the demo notebooks on their local machine (optional dependencies apply), or use the software in their own projects by simply importing it:
 ```python
-import pyproject_qiskit
+import <IMPORT-NAME>
 ```
 From the terminal:
-```
+```sh
 $ python
 Python 3.10.5 (main, Jun 23 2022, 17:15:25) [Clang 13.1.6 (clang-1316.0.21.2.5)] on darwin
 Type "help", "copyright", "credits" or "license" for more information.
->>> import pyproject_qiskit
->>> print(pyproject_qiskit)
-<module 'pyproject_qiskit' from '.venv/lib/python3.10/site-packages/pyproject_qiskit/__init__.py'>
+>>> import <IMPORT-NAME>
+>>> print(<IMPORT-NAME>)
+<module '<IMPORT-NAME>' from '.venv/lib/python3.10/site-packages/<IMPORT-NAME>/__init__.py'>
 ```
-For instructions on how to use this package see [here](docs/reference_guide.md).
+For instructions on how to use this software see our [reference guide](docs/reference_guide.md).