Avoid exporting incorrect PyInit_* symbols (#12889)

Using the `#[pymodule]` derive macro in PyO3 0.21 always causes a
`PyInit_*` symbol with a matching name to be exported in the output
`cdylib`.  This is required for the top-level module, in order for
Python to import it---it needs to know which symbol in a shared library
file it should call---but submodules must be manually initialised, so do
not need it.  Including it is typically harmless (and something we've
been doing for a long time), but it is technically against the coding
rules for CPython extensions[^1].

Recent versions of `abi3audit` (0.0.11+) have tightened their symbol
checkers to better match the CPython guidelines, which causes our wheels
to be rejected by their audits.  This is, in theory, not a break of abi3
because CPython could never introduce an API-elvel `PyInit_*` function
themselves without causing problems, so there ought to be no problems
for our users, even with future Python versions. That said, we still
want to pass the audit, because the coding guidelines are useful.

This commit is not the cleanest way of doing things.  PyO3 0.22 includes
a `#[pymodule(submodule)]` option on the attribute macro, which lets us
use all the standard code generation while suppressing the unnecessary
`PyInit_*` symbol.  When we are ready to move to PyO3 0.22, we probably
want to revert this commit to switch to that form.

[^1]: https://docs.python.org/3/c-api/intro.html

(cherry picked from commit 120b73d)

crates/accelerate/src/convert_2q_block_matrix.rs

@@ -145,7 +145,6 @@ pub fn collect_2q_blocks_filter(node: &Bound<PyAny>) -> Option<bool> {
     }
 }
 
-#[pymodule]
 pub fn convert_2q_block_matrix(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(blocks_to_matrix))?;
     m.add_wrapped(wrap_pyfunction!(collect_2q_blocks_filter))?;

crates/accelerate/src/dense_layout.rs

@@ -244,7 +244,6 @@ pub fn best_subset_inner(
     [rows, cols, best_map]
 }
 
-#[pymodule]
 pub fn dense_layout(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(best_subset))?;
     Ok(())

crates/accelerate/src/error_map.rs

@@ -111,7 +111,6 @@ impl ErrorMap {
     }
 }
 
-#[pymodule]
 pub fn error_map(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_class::<ErrorMap>()?;
     Ok(())

crates/accelerate/src/euler_one_qubit_decomposer.rs

@@ -1059,7 +1059,6 @@ pub fn collect_1q_runs_filter(node: &Bound<PyAny>) -> bool {
         }
 }
 
-#[pymodule]
 pub fn euler_one_qubit_decomposer(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(params_zyz))?;
     m.add_wrapped(wrap_pyfunction!(params_xyx))?;

crates/accelerate/src/isometry.rs

@@ -345,7 +345,6 @@ fn b(k: usize, s: usize) -> usize {
     k - (a(k, s) * 2_usize.pow(s as u32))
 }
 
-#[pymodule]
 pub fn isometry(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(diag_is_identity_up_to_global_phase))?;
     m.add_wrapped(wrap_pyfunction!(find_squs_for_disentangling))?;

crates/accelerate/src/nlayout.rs

@@ -216,7 +216,6 @@ impl NLayout {
     }
 }
 
-#[pymodule]
 pub fn nlayout(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_class::<NLayout>()?;
     Ok(())

crates/accelerate/src/optimize_1q_gates.rs

@@ -90,7 +90,6 @@ pub fn compose_u3_rust(
     out_angles
 }
 
-#[pymodule]
 pub fn optimize_1q_gates(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(compose_u3_rust))?;
     Ok(())

crates/accelerate/src/pauli_exp_val.rs

@@ -193,7 +193,6 @@ pub fn density_expval_pauli_with_x(
     }
 }
 
-#[pymodule]
 pub fn pauli_expval(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(expval_pauli_no_x))?;
     m.add_wrapped(wrap_pyfunction!(expval_pauli_with_x))?;

crates/accelerate/src/results/mod.rs

@@ -16,7 +16,6 @@ pub mod marginalization;
 use pyo3::prelude::*;
 use pyo3::wrap_pyfunction;
 
-#[pymodule]
 pub fn results(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(marginalization::marginal_counts))?;
     m.add_wrapped(wrap_pyfunction!(marginalization::marginal_distribution))?;

crates/accelerate/src/sabre/mod.rs

@@ -106,7 +106,6 @@ impl BlockResult {
     }
 }
 
-#[pymodule]
 pub fn sabre(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(route::sabre_routing))?;
     m.add_wrapped(wrap_pyfunction!(layout::sabre_layout_and_routing))?;

crates/accelerate/src/sampled_exp_val.rs

@@ -87,7 +87,6 @@ pub fn sampled_expval_complex(
     Ok(out.re)
 }
 
-#[pymodule]
 pub fn sampled_exp_val(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(sampled_expval_float))?;
     m.add_wrapped(wrap_pyfunction!(sampled_expval_complex))?;

crates/accelerate/src/sparse_pauli_op.rs

@@ -819,7 +819,6 @@ impl_to_matrix_sparse!(
     u64
 );
 
-#[pymodule]
 pub fn sparse_pauli_op(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(unordered_unique))?;
     m.add_wrapped(wrap_pyfunction!(decompose_dense))?;

crates/accelerate/src/star_prerouting.rs

@@ -207,7 +207,6 @@ fn apply_swap(
     }
 }
 
-#[pymodule]
 pub fn star_prerouting(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(star_preroute))?;
     Ok(())

crates/accelerate/src/stochastic_swap.rs

@@ -335,7 +335,6 @@ pub fn swap_trials(
     Ok((best_edges, best_layout, best_depth))
 }
 
-#[pymodule]
 pub fn stochastic_swap(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(swap_trials))?;
     m.add_class::<EdgeCollection>()?;

crates/accelerate/src/synthesis/clifford/mod.rs

@@ -57,7 +57,6 @@ fn synth_clifford_bm(py: Python, clifford: PyReadonlyArray2<bool>) -> PyResult<C
     CircuitData::from_standard_gates(py, num_qubits as u32, clifford_gates, Param::Float(0.0))
 }
 
-#[pymodule]
 pub fn clifford(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(synth_clifford_greedy, m)?)?;
     m.add_function(wrap_pyfunction!(synth_clifford_bm, m)?)?;

crates/accelerate/src/synthesis/linear/mod.rs

@@ -175,7 +175,6 @@ fn check_invertible_binary_matrix(py: Python, mat: PyReadonlyArray2<bool>) -> Py
     Ok(out.to_object(py))
 }
 
-#[pymodule]
 pub fn linear(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(gauss_elimination_with_perm))?;
     m.add_wrapped(wrap_pyfunction!(gauss_elimination))?;

crates/accelerate/src/synthesis/mod.rs

@@ -15,12 +15,19 @@ pub mod linear;
 mod permutation;
 
 use pyo3::prelude::*;
-use pyo3::wrap_pymodule;
 
-#[pymodule]
 pub fn synthesis(m: &Bound<PyModule>) -> PyResult<()> {
-    m.add_wrapped(wrap_pymodule!(linear::linear))?;
-    m.add_wrapped(wrap_pymodule!(permutation::permutation))?;
-    m.add_wrapped(wrap_pymodule!(clifford::clifford))?;
+    let linear_mod = PyModule::new_bound(m.py(), "linear")?;
+    linear::linear(&linear_mod)?;
+    m.add_submodule(&linear_mod)?;
+
+    let permutation_mod = PyModule::new_bound(m.py(), "permutation")?;
+    permutation::permutation(&permutation_mod)?;
+    m.add_submodule(&permutation_mod)?;
+
+    let clifford_mod = PyModule::new_bound(m.py(), "clifford")?;
+    clifford::clifford(&clifford_mod)?;
+    m.add_submodule(&clifford_mod)?;
+
     Ok(())
 }

crates/accelerate/src/synthesis/permutation/mod.rs

@@ -114,7 +114,6 @@ pub fn _synth_permutation_depth_lnn_kms(
     )
 }
 
-#[pymodule]
 pub fn permutation(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(_validate_permutation, m)?)?;
     m.add_function(wrap_pyfunction!(_inverse_pattern, m)?)?;

crates/accelerate/src/two_qubit_decompose.rs

@@ -2254,7 +2254,6 @@ pub fn local_equivalence(weyl: PyReadonlyArray1<f64>) -> PyResult<[f64; 3]> {
     Ok([g0_equiv + 0., g1_equiv + 0., g2_equiv + 0.])
 }
 
-#[pymodule]
 pub fn two_qubit_decompose(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(_num_basis_gates))?;
     m.add_wrapped(wrap_pyfunction!(two_qubit_decompose_up_to_diagonal))?;

crates/accelerate/src/uc_gate.rs

@@ -156,7 +156,6 @@ pub fn dec_ucg_help(
     )
 }
 
-#[pymodule]
 pub fn uc_gate(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(dec_ucg_help))?;
     Ok(())

crates/accelerate/src/utils.rs

@@ -41,7 +41,6 @@ pub fn eigenvalues(py: Python, unitary: PyReadonlyArray2<Complex<f64>>) -> PyObj
         .into()
 }
 
-#[pymodule]
 pub fn utils(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(eigenvalues))?;
     Ok(())

crates/accelerate/src/vf2_layout.rs

@@ -106,7 +106,6 @@ pub fn score_layout(
     Ok(1. - fidelity)
 }
 
-#[pymodule]
 pub fn vf2_layout(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(score_layout))?;
     m.add_class::<EdgeList>()?;

crates/circuit/src/lib.rs

@@ -56,8 +56,7 @@ impl From<Clbit> for BitType {
     }
 }
 
-#[pymodule]
-pub fn circuit(m: Bound<PyModule>) -> PyResult<()> {
+pub fn circuit(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_class::<circuit_data::CircuitData>()?;
     m.add_class::<dag_node::DAGNode>()?;
     m.add_class::<dag_node::DAGInNode>()?;

crates/pyext/src/lib.rs

@@ -11,7 +11,6 @@
 // that they have been altered from the originals.
 
 use pyo3::prelude::*;
-use pyo3::wrap_pymodule;
 
 use qiskit_accelerate::{
     convert_2q_block_matrix::convert_2q_block_matrix, dense_layout::dense_layout,
@@ -24,29 +23,40 @@ use qiskit_accelerate::{
     vf2_layout::vf2_layout,
 };
 
+#[inline(always)]
+#[doc(hidden)]
+fn add_submodule<F>(m: &Bound<PyModule>, constructor: F, name: &str) -> PyResult<()>
+where
+    F: FnOnce(&Bound<PyModule>) -> PyResult<()>,
+{
+    let new_mod = PyModule::new_bound(m.py(), name)?;
+    constructor(&new_mod)?;
+    m.add_submodule(&new_mod)
+}
+
 #[pymodule]
 fn _accelerate(m: &Bound<PyModule>) -> PyResult<()> {
-    m.add_wrapped(wrap_pymodule!(qiskit_circuit::circuit))?;
-    m.add_wrapped(wrap_pymodule!(qiskit_qasm2::qasm2))?;
-    m.add_wrapped(wrap_pymodule!(qiskit_qasm3::qasm3))?;
-    m.add_wrapped(wrap_pymodule!(convert_2q_block_matrix))?;
-    m.add_wrapped(wrap_pymodule!(dense_layout))?;
-    m.add_wrapped(wrap_pymodule!(error_map))?;
-    m.add_wrapped(wrap_pymodule!(euler_one_qubit_decomposer))?;
-    m.add_wrapped(wrap_pymodule!(isometry))?;
-    m.add_wrapped(wrap_pymodule!(nlayout))?;
-    m.add_wrapped(wrap_pymodule!(optimize_1q_gates))?;
-    m.add_wrapped(wrap_pymodule!(pauli_expval))?;
-    m.add_wrapped(wrap_pymodule!(synthesis))?;
-    m.add_wrapped(wrap_pymodule!(results))?;
-    m.add_wrapped(wrap_pymodule!(sabre))?;
-    m.add_wrapped(wrap_pymodule!(sampled_exp_val))?;
-    m.add_wrapped(wrap_pymodule!(sparse_pauli_op))?;
-    m.add_wrapped(wrap_pymodule!(star_prerouting))?;
-    m.add_wrapped(wrap_pymodule!(stochastic_swap))?;
-    m.add_wrapped(wrap_pymodule!(two_qubit_decompose))?;
-    m.add_wrapped(wrap_pymodule!(uc_gate))?;
-    m.add_wrapped(wrap_pymodule!(utils))?;
-    m.add_wrapped(wrap_pymodule!(vf2_layout))?;
+    add_submodule(m, qiskit_circuit::circuit, "circuit")?;
+    add_submodule(m, qiskit_qasm2::qasm2, "qasm2")?;
+    add_submodule(m, qiskit_qasm3::qasm3, "qasm3")?;
+    add_submodule(m, convert_2q_block_matrix, "convert_2q_block_matrix")?;
+    add_submodule(m, dense_layout, "dense_layout")?;
+    add_submodule(m, error_map, "error_map")?;
+    add_submodule(m, euler_one_qubit_decomposer, "euler_one_qubit_decomposer")?;
+    add_submodule(m, isometry, "isometry")?;
+    add_submodule(m, nlayout, "nlayout")?;
+    add_submodule(m, optimize_1q_gates, "optimize_1q_gates")?;
+    add_submodule(m, pauli_expval, "pauli_expval")?;
+    add_submodule(m, synthesis, "synthesis")?;
+    add_submodule(m, results, "results")?;
+    add_submodule(m, sabre, "sabre")?;
+    add_submodule(m, sampled_exp_val, "sampled_exp_val")?;
+    add_submodule(m, sparse_pauli_op, "sparse_pauli_op")?;
+    add_submodule(m, star_prerouting, "star_prerouting")?;
+    add_submodule(m, stochastic_swap, "stochastic_swap")?;
+    add_submodule(m, two_qubit_decompose, "two_qubit_decompose")?;
+    add_submodule(m, uc_gate, "uc_gate")?;
+    add_submodule(m, utils, "utils")?;
+    add_submodule(m, vf2_layout, "vf2_layout")?;
     Ok(())
 }

crates/qasm2/src/lib.rs

@@ -123,7 +123,6 @@ fn bytecode_from_file(
 /// An interface to the Rust components of the parser stack, and the types it uses to represent the
 /// output.  The principal entry points for Python are :func:`bytecode_from_string` and
 /// :func:`bytecode_from_file`, which produce iterables of :class:`Bytecode` objects.
-#[pymodule]
 pub fn qasm2(module: &Bound<PyModule>) -> PyResult<()> {
     module.add_class::<bytecode::OpCode>()?;
     module.add_class::<bytecode::UnaryOpCode>()?;

crates/qasm3/src/lib.rs

@@ -153,7 +153,6 @@ pub fn load(
 
 /// Internal module supplying the OpenQASM 3 import capabilities.  The entries in it should largely
 /// be re-exposed directly to public Python space.
-#[pymodule]
 pub fn qasm3(module: &Bound<PyModule>) -> PyResult<()> {
     module.add_function(wrap_pyfunction!(loads, module)?)?;
     module.add_function(wrap_pyfunction!(load, module)?)?;