Move ParameterVector to Rust

`ParameterVector` was previously a pure-Python concept, even though the
Rust-space `Symbol` necessarily had to track an internal backreference
to a vector Python object in order to convert itself to Python later.
This hidden dependence on the Python interpreter was the root cause of a
panicking bug in Qiskit 2.4[^1].

All `ParameterVectorElement`s in Python space have names and UUIDs that
are pure functions of the underlying vector and the element's index.
Now that this information is available in Rust space, it is far more
efficient to simply not store all this derived information, but
calculate it on the fly, as needed.  This motivated the change in
`Symbol` to an `enum`: the logic was _already_ handling the two cases of
"standalone" and "element", but this formally separates them to avoid
storing unnecessary data.  Doing this alone is already a performance
benefit: construction of a `list(ParameterVector("a", 10_000))` (to
ensure all the same Python-space objects are created) went from 7.7ms
to 1.4ms on my machine (~5x speedup).

This work here is far more aggressive at threading through shared `Arc`
references of both `Symbol` and `SymbolVector`.  The `Arc<SymbolVector>`
is necessary for correctness in Python space, not just performance: we
must have `all(el.vector == els[0].vector for el in els)`, and we don't
want to have to cache more Python objects within `Symbol` to achieve
that.  Unfortunately, `ParameterVector` never implemented true equality
(only the default referential equality that Python uses to make
mutable-state objects safely hashable by default), so we certainly need
some other stable reference that can be shared.

The previous Python-space constructions of `PyParameter` and
`PyParameterVectorElement` had not been done entirely correctly with
respect to subclassing; the same (cloned) `Symbol` was present in
multiple places, which was two more allocations than necessary (most
places in Rust use `Arc<Symbol>`, which can be near-freely cloned).
This corrects it so that `PyParameterVectorElement` is now just a simple
marker type, and the majority of the Rust logic needn't concern itself
with it at all.

The `AtomicUsize` used for the length of `SymbolVector` is to support
the unfortunate `ParameterVector.resize` operation from Python space.
The atomic operation makes the whole logic safe from data races, but
does nothing to solve the potential race condition of two places
querying a vector its length concurrently and getting different answers,
or the problem that shortening the vector can invalidate already-held
references to `ParameterVectorElement`s or `Symbol`s (a problem that was
pre-existing in Python).  The `resize` in-place method is fairly
fundamentally unsound for these reasons, and we should consider removing
it; it's only used in the deprecated `NLocal` subclass of
`BlueprintCircuit`, and that use can probably be replaced by a simple
lazier construction of the vector, or a complete object replacement
rather than mutation.

[^1]: 16c8088: Fix panic in `RemoveIdentityEquivalent` with `ParameterVector` global phase (gh-16054)

Author: jakelishman

crates/cext/src/param.rs

@@ -47,7 +47,7 @@ pub unsafe extern "C" fn qk_param_new_symbol(name: *const c_char) -> *mut Param
         // Per documentation, the name cannot be empty.
         panic!("Invalid empty name.");
     } else {
-        let symbol = Symbol::new(name, None, None);
+        let symbol = Symbol::standalone(name.to_owned(), None);
         let expr = ParameterExpression::from_symbol(symbol);
         let param = Param::ParameterExpression(Arc::new(expr));
         Box::into_raw(Box::new(param))

crates/cext/src/transpiler/target.rs

@@ -509,7 +509,7 @@ impl TargetEntry {
                     .map(|i| {
                         let op_name = operation.name();
                         Param::ParameterExpression(Arc::new(ParameterExpression::from_symbol(
-                            Symbol::new(format!("{op_name}_param_{i}").as_str(), None, None),
+                            Symbol::standalone(format!("{op_name}_param_{i}"), None),
                         )))
                     })
                     .collect(),

crates/circuit/src/lib.rs

@@ -240,6 +240,7 @@ pub fn circuit(m: &Bound<PyModule>) -> PyResult<()> {
     m.add_class::<parameter::parameter_expression::PyParameterExpression>()?;
     m.add_class::<parameter::parameter_expression::PyParameter>()?;
     m.add_class::<parameter::parameter_expression::PyParameterVectorElement>()?;
+    m.add_class::<parameter::parameter_expression::PyParameterVector>()?;
     m.add_class::<parameter::parameter_expression::OpCode>()?;
     m.add_class::<parameter::parameter_expression::OPReplay>()?;
     let classical_mod = PyModule::new(m.py(), "classical")?;

crates/circuit/src/operations.rs

@@ -146,11 +146,7 @@ impl Param {
                             .getattr(parameters_attr)?
                             .try_iter()?
                             .map(|elem| {
-                                let elem = elem?;
-                                let py_param_bound = elem.cast::<PyParameter>()?;
-                                let py_param = py_param_bound.borrow();
-                                let symbol = py_param.symbol();
-                                Ok(symbol.clone())
+                                Ok(Symbol::clone(&elem?.cast_into::<PyParameter>()?.borrow().0))
                             })
                             .collect::<PyResult<_>>()?;
                         Ok(Box::new(collected.into_iter()))