Deprecates StochasticSwap and suggests the use of SabreSwap

[danielbultrini]

Summary

I added depreciation warnings for issue #12552 and modified unit tests to capture the new errors. Documentation with examples has also been added.

Details and comments

I have added a deprecation warning to the StochasticSwap class and a description of how to change things. All relevant tests were made to capture the warning, but some tests which check all different types of these passes (i.e. Sabre, look ahead) where split so that the stochastic method may easily be removed in future. In one class of test (test_mappers.py) StochasticSwap had to be removed, as the method used to run the tests made it prohibitively hard to easily check for warnings in the stochastic case exclusively.

[qiskit-bot]

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

One or more of the following people are relevant to this code:

• @Qiskit/terra-core

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[ElePT]

Thanks a lot @danielbultrini, the PR looks really good, I just added a tiny suggestion for a typo, and you need to sign the CLA agreement mentioned in the comment above for us to be able to merge it into Qiskit!

(note that you can apply the suggestion directly by clicking on the "Commit suggestion" button under it)

[danielbultrini]

Thanks @ElePT ! After a bit more work, all tests passed. I signed the CLA, but for some reason it's still showing as unsigned (although another bot comment says it's signed). It was a great learning experience to go through this process

[ElePT]

Thanks again @danielbultrini :) The PR is almost there, I just added a few minor comments to polish the final details. I think that the CLA shouldn't be an issue, as the license CI check passes. As you have seen, deprecations can be trickier to handle than they seem, so this is really good work!!

[ElePT]

I just applied some minor suggestions for the wording of the TODOs, and I think we are good to go!! Approving the PR :)

[coveralls]

Pull Request Test Coverage Report for Build 10469003353

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 2 of 2 (100.0%) changed or added relevant lines in 1 file are covered.
• 3 unchanged lines in 2 files lost coverage.
• Overall coverage increased (+0.03%) to 89.576%

---

Files with Coverage Reduction	New Missed Lines	%
crates/accelerate/src/two_qubit_decompose.rs	1	90.69%
crates/qasm2/src/lex.rs	2	91.98%

Totals
Change from base Build 10459812488:	0.03%
Covered Lines:	67591
Relevant Lines:	75457

---

💛 - Coveralls