Deprecate opt_a1, opt_a2, and non-decomposer callables in qs_decomposition (Qiskit 2.3)

[AbdullahKazi500]

• I have added the tests to cover my changes.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
  -->

Summary

This PR introduces deprecation warnings for parameters opt_a1, opt_a2, and for passing non-decomposer callable objects to decomposer_1q and decomposer_2q in the qs_decomposition function within the qiskit.synthesis.qsd.qs_decomposition module.
These parameters and behaviors are now officially deprecated as of Qiskit 2.3.0 and will be removed in Qiskit 3.0.
Fixes #15004

Details and comments

Changes introduced

Added DeprecationWarnings for:

opt_a1 and opt_a2 parameters.

Non-instance callables passed as decomposer_1q or decomposer_2q.

Updated docstring to clearly document the deprecation timeline and future behavior.

Improved type checks for decomposer arguments (OneQubitEulerDecomposer and TwoQubitBasisDecomposer only).

Maintained backward compatibility for existing behavior in Qiskit 2.x.

Refactored logic for automatic optimization selection when deprecated parameters are omitted.

Release Notes

Deprecated

opt_a1 and opt_a2 parameters in qs_decomposition.

Passing callable objects as decomposer_1q or decomposer_2q instead of decomposer instances.

Will be removed in: Qiskit 3.0

AI tool used: Claude — for code modernization and documentation updates.

[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

[ShellyGarion]

@AbdullahKazi500 - thanks for your contribution to qiskit!

First, I see that there are some lint errors.
Second, is there a reason that you removed some comments and docstrings? these are internal and help undertanding the algorithm. Optimizations A1 and A2 are still done but are internal and cannot be set by the user.
Third, could you add some tests that asserts that the warnings are raised?

[AbdullahKazi500]

@AbdullahKazi500 - thanks for your contribution to qiskit!

First, I see that there are some lint errors. Second, is there a reason that you removed some comments and docstrings? these are internal and help undertanding the algorithm. Optimizations A1 and A2 are still done but are internal and cannot be set by the used. Third, could you add some tests that asserts that the warnings are raised?

Hi yes the changes were not necessary I will revert back those changes

[coveralls]

Pull Request Test Coverage Report for Build 18882837746

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

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 30 unchanged lines in 3 files lost coverage.
• Overall coverage decreased (-0.02%) to 88.173%

---

Files with Coverage Reduction	New Missed Lines	%
crates/circuit/src/parameter/symbol_expr.rs	1	73.15%
crates/qasm2/src/lex.rs	5	91.52%
crates/qasm2/src/parse.rs	24	96.15%

Totals
Change from base Build 18881330737:	-0.02%
Covered Lines:	93646
Relevant Lines:	106207

---

💛 - Coveralls

[AbdullahKazi500]

@AbdullahKazi500 - thanks for your contribution to qiskit!

First, I see that there are some lint errors. Second, is there a reason that you removed some comments and docstrings? these are internal and help undertanding the algorithm. Optimizations A1 and A2 are still done but are internal and cannot be set by the user. Third, could you add some tests that asserts that the warnings are raised?

Hi Shelly I have maintained all the other docstrings and fixed opt_a1 and opt_a2 exposed to user where should I add the tests

[ShellyGarion]

Hi Shelly I have maintained all the other docstrings and fixed opt_a1 and opt_a2 exposed to user where should I add the tests

thanks @AbdullahKazi500, the tests are located here:
https://github.com/Qiskit/qiskit/blob/main/test/python/synthesis/test_qsd_synthesis.py

[1ucian0]

Did you consider using deprecate_args instead? https://github.com/Qiskit/qiskit/blob/main/qiskit/utils/deprecation.py#L105

[ShellyGarion]

@AbdullahKazi500 - are you still working on this PR?

[AbdullahKazi500]

@AbdullahKazi500 - are you still working on this PR?

Hi Yes I was caught up in some work and did not got the time to commit on this PR , I just got free with my work and will be focusing on completing this PR

[ShellyGarion]

@AbdullahKazi500 - would it be possible to complete this PR until the end of April 2026, so that it will be ready on time for the next release?