diff --git a/0012-algorithms-migration.md b/0012-algorithms-migration.md new file mode 100644 index 0000000..52590ab --- /dev/null +++ b/0012-algorithms-migration.md @@ -0,0 +1,182 @@ +# Plan to move `Qiskit/qiskit-terra/algorithms` module to `Qiskit-community/qiskit-algorithms` independent repo + +| **Status** | **Proposed** | +|:------------------|:------------------------------------------------------------------------------------------| +| **RFC #** | #### | +| **Authors** | [Elena Peña Tapia](https://github.com/ElePT), [Steve Wood](https://github.com/woodsp-ibm) | +| **Submitted** | 2023-07-05 | +| **Updated** | 2023-08-28 | + + +## Summary + +This RFC was created to document discussions concerning the future of the `qiskit.algorithms` module. +This module provides a series of interfaces and implementations of commonly used quantum algorithms based on +Qiskit's core components. Historically, the module was created as part of Qiskit Aqua, together with the now +community-based application modules (Nature, Machine Learning, Optimization, Finance). +It [currently "lives" in `qiskit-terra`](https://github.com/Qiskit/qiskit), +and over the past year has been refactored to use the Qiskit Primitives and sustain the +Opflow and Quantum Instance deprecations. + +The content of `qiskit.algorithms` is heterogeneous. Some components are algorithm implementations, while others +are "sub-routines" or algorithm utilities, such as gradients, optimizers or state fidelities. Some of these +utilities are implementatons from scratch, others are wrappers over commonly used libraries (such as the +SciPy optimizers). + +With Qiskit moving towards a leaner definition and focusing on primitives as quantum hardware access model, +the future of `qiskit.algorithms` is being revisited. +The classes in the module tend to hide the primitives interfaces and serve as convenience wrappers +for abstractions, beyond the current definition of Qiskit. +As such, they do provide value to users to it would be important to +find a better suiting location for them while minimizing the disruption caused to users. + +**Note**: In this document, the terms `qiskit-terra` and `qiskit` are interchangeable. + +## Design Proposal + +There are several design decisions to be made as part of this "`qiskit.algorithms` revision": + +1. Which classes stay in `qiskit-terra` +2. Where do they stay within `qiskit-terra` (i.e. do they stay in `qiskit.algorithms`? or is the module +renamed or split to better define its purpose?) +3. Where do the "non-chosen" classes go + +We have to keep in mind that these algorithms are extensively used by +the community and until now, they have been one of the main access points to our stack. For example, the +`MinimumEigensolver` class is a fundamental +dependency for Qiskit Nature, which relies on this definition to interface with classical chemistry codes via +plugins. + +Even if we stop their maintenance, it would still be highly valuable to have a self-contained, installable package +that the community can access and add as a dependency to avoid having to reimplement research code or libraries. + +### Main Idea + +We believe that fastest way to disentangle `qiskit.algorithms` from `qiskit-terra` while causing minimal +disruption to users would +be to create a standalone `qiskit-algorithms` repo with a similar setup to the applications repos (including CI, docs...), +perform a history-preserving copy of the content of `qiskit.algorithms` to `qiskit_algorithms`, and document +the migration path by raising a deprecation warning asking users to change the import. + +This repository can be created regardless of whether we decide to keep some algorithms in `qiskit-terra` or not. +In the event that we decided to keep certain algorithms in `qiskit-terra`, there would be two possible paths: + +**Path 1** + +1. All contents of `qiskit.algorithms` are moved over to `qiskit-algorithms`, and the module as a whole +is deprecated. +2. Some components are moved back to `qiskit-terra`, potentially to a new location +(`qiskit.gradients`, `qiskit.optimizers`, `qiskit.state_fidelities`...), and are potentially refactored during this move. + +This alternative allows to have a "clean slate" for developers with the downside of potentially moving some components +out of qiskit and back into qiskit again in a short period of time. The migration path is easier in this alternative, but +deprecations are a huge hassle for users, and if we +are sure of which components we want to keep, (if we want to keep any) this might not +be the best way (or the most popular) from a user-friendliness point of view. + +**Path 2** + +1. Only part of the contents of `qiskit.algorithms` are moved over to `qiskit-algorithms`, and classes +are deprecated individually. +2. This allows for refactorings to happen in-place as a second step + +This alternative is more conservative, and requires a better understanding of what the future components of +`qiskit.algorithms` will be, and whether we want to keep the module's name and current structure. The plans +to release Qiskit 1.0 should also be taken into account, as they imply a commitment to whatever is kept +in Qiskit. + +**Decision** + +After analizing pros and cons for both options, our current plan is to design a migration plan that +follows **Path 1**. This allows us to focus on the move to the new repository as an initial step, without +deciding specifically which algorithms/utilities might be added back to Qiskit. +Should new considerations be taken into account, this plan could change. + +### Migration plan + +**Repos immediately affected by the plan**: `Qiskit/qiskit-terra` and `Qiskit/qiskit-tutorials` + +### qiskit-terra + +1. Open a PR to add a single deprecation message telling users to change their imports +from `qiskit.algorithms` to `qiskit_algorithms`. The code will continue existing +in `qiskit-terra` until the deprecation period is over [Blocker: release of `qiskit_algorithms-0.1.0`, +see below]. +2. What should we do with the algorithms migration guide? we could leave it in terra during the deprecation period, +for users still using `qiskit.algorithms` but make a copy in `qiskit-algorithms` (maybe the copy needs some editing +for references etc). After the deprecation period, we can remove it from terra. +3. What about algorithms that depend on already deprecated code (i.e opflow)? +Given that the deprecated code will still be available in `qiskit.algorithms`, we can just migrate the non-deprecated +code to the new location and warn users about updating their code before migrating to the new package +(direct to migration guides). This will provide a "clean slate" for `qiskit_algorithms`. +4. During the deprecation period, we can focus on moving issues, closing pending PRs, and finishing up other details + +### qiskit-tutorials + +1. There is already a plan to relocate the tutorials from `qiskit-tutorials` to `qiskit-terra` +https://github.com/Qiskit/qiskit-tutorials/issues/1473. Instead of relocating to terra, we propose to move the tutorials +to `qiskit-algorithms/docs` and be published as part of its docs as we do for Nature, ML et al. +2. During the deprecation period, a redirect could be set up to go from `qiskit.org/documentation/tutorials/algorithms/*` to +`qiskit.org/ecosystem/algorithms/tutorials/index.html` +3. Which tutorials should be moved? All tutorials that use `qiskit_applications`. Other tutorials that build algorithms +from scratch (such as https://github.com/Qiskit/qiskit-tutorials/blob/master/tutorials/algorithms/09_IQPE.ipynb) are +better suited as educational material. + + +### qiskit-algorithms + +1. Create a new `qiskit-algorithms` repo and perform a history preserving copy plus a move, and whatever namespace +fix-ups are needed for imports, deprecation messages of the old algos etc. We have done this history preserving +copy in the past. +2. Perform a history preserving copy of the relevant tutorials in `qiskit-tutorials` plus necessary code updates +(imports, etc) +3. This new repo would need CI setup, the docs setup, etc, so they can +publish out like apps repos do. And as mentioned above, the docs can include a copy of the algorithms migration - +maybe the short url points to this published copy. + +### docs +1. Similarly to the application modules, the algorithm docs could be rendered in `qiskit.org/ecosystem/algorithms` +2. During the deprecation, a redirect could be set up to go from `qiskit.org/documentation/` to `qiskit.org/ecosystem/algorithms` + + +### Alternatives considered but disregarded + +1. Splitting `qiskit.algorithms`, keeping some algorithms, moving others to different locations (such as the apps modules): +This idea was disregarded because of the disruption it will cause to users, to libraries for which `qiskit-algorithms` is +a dependency (i.e, apps modules), and the lack of consensus on which algorithms go where. +2. Making `qiskit-algorithms` a git submodule of Terra instead of doing a redirect. The sub-module is linked by a +specific commit as far as Steve recalls and its something that got discussed in the early days but was not well liked. +The namespace strategy followed with qiskit.providers.aer redirecting to qiskit_aer works and keeps +things more independent. + + +### Timeline + +As this is an urgent move, the deprecations and new installable package should be in place for the terra 0.25 release. +Docs can be updated in between releases. +The deprecation period should allow for the final decoupling to happen for 0.26. + +## Open Questions + +There are 2 main open questions left: + +1. Are any algorithms going to stay in terra? +2. If so, where would they stay? + +Under the assumption that we only want to keep +"fundamental building blocks" for algorithm design, our current proposal would be to maintain +sub-routines and utilities (gradients, fidelities, optimizers that are not wrappers), +and replace specific algorithm implementations with well crafted tutorials/documentation. Because of the independent +`qiskit-algorithms` repository, users that relied on other algorithm implementations would still have access to these +classes. + +Specifically, if we look at the current non-deprecated contents of the module, the proposed distribution would be: + +- `amplitude_estimators` -> tutorial +- `eigensolvers` -> tutorial +- `gradients` -> **utility that stays** +- `minimum_eigensolvers` -> tutorial +- `optimizers` -> **those that don't wrap scipy ara a utility that stays** +- `phase_estimators` -> tutorial +- `state_fidelities` -> **utility that stays** +- `time_evolvers` -> tutorial