Prepare qiskit/transpiler/graysynth.py for deprecation in next release

[ShellyGarion]

Summary

As described in #9445 we should properly deprecate qiskit/transpiler/graysynth.py that currently contains the two functions
cnot_synth and gray_synth.

Details and comments

• The function cnot_synth is refactored to synth_cnot_count_full_pmh in the file qiskit/synthesis/linear/cnot_synth.py .
• The function graysynth is refactored to synth_cnot_phase_aam in the file qiskit/synthesis/linear_phase/graysynth.py .

See also #9667

[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 the following people are requested to review this:

• @Qiskit/terra-core

[coveralls]

Pull Request Test Coverage Report for Build 4722520110

• 59 of 60 (98.33%) changed or added relevant lines in 7 files are covered.
• 21 unchanged lines in 3 files lost coverage.
• Overall coverage decreased (-0.02%) to 85.806%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
qiskit/synthesis/linear/cnot_synth.py	48	49	97.96%

Files with Coverage Reduction	New Missed Lines	%
qiskit/transpiler/passes/synthesis/unitary_synthesis.py	1	95.37%
crates/qasm2/src/lex.rs	2	90.89%
crates/qasm2/src/parse.rs	18	96.65%

Totals
Change from base Build 4721576551:	-0.02%
Covered Lines:	70516
Relevant Lines:	82181

---

💛 - Coveralls

[Eric-Arellano]

We'll want to use the new helpers from #9676 (temporarily blocked by #9790)

[Eric-Arellano]

The deprecation decorators look good to me. I didn't review the rest.

[jakelishman]

These functions don't look eligible for deprecation to me in Terra 0.24, since this PR is the one that's adding their replacement. In the Qiskit deprecation policy, the rule is that the replacement needs to be in place for a full minor release cycle before a warning can be issued - the reason is so that it's always possible to have valid code for the most recent two minor releases of Terra, rather than requiring all users/downstream packages to depend on the bleeding edge if they want to avoid warnings.

For example, in all Qiskit projects we have warnings treated as errors in our test suite, and several projects test against Terra main as well. If we did deprecations at the same time as the replacement, those projects couldn't have code that supports both the current dev version and the current release version simultaneously.

[alexanderivrii]

@ShellyGarion has asked me to look at the code organization and the names of the functions. This looks good and consistent to what we did in the past. I have not look at the deprecation-related content.

[jakelishman]

I pushed up a commit that just adds a comment on the re-export to remind us why it exists and comment that it's eligible for deprecation later. Other than that, I think we're good here now. Thanks Shelly.