ParameterPool

class ParameterPool

Bases: object

Process-global registry of OPNIC packet targets and the bound Quarc module.

Note

Single-thread constraint. ParameterPool stores all of its state on class-level attributes. It is designed for single-threaded use — one Quarc session per process at a time. There is no per-thread isolation; running multiple QUA programs concurrently from the same process is not supported. Per-thread isolation via threading.local is a planned future enhancement.

classmethod iter_measurement_outcome_tables() → Iterator[Any]

Yield live MeasurementOutcomeTable instances (debug/introspection).

classmethod iter_measurement_register_fields() → Iterator[Any]

Yield live MeasurementRegisterField handles (debug/introspection).

classmethod lookup_runtime_parameter(name: str) → 'Parameter' | None

Return the runtime Parameter named name (excludes measurement fields).

classmethod reset() → None

Clear all pool state — runtime registry, measurement registries, and Quarc module.

classmethod guard_single_program_opnic(token: Any, *, table_name: str = '<unknown>') → None

Enforce that OPNIC structs are declared under a single QUA program scope.

The first OPNIC declare() records its program-scope token; a later declare() under a different token raises. Declaring multiple OPNIC tables in the same program is fine (same token). Call reset() to start a new program.

classmethod iter_opnic_parameter_tables() → List['ParameterTable']

Return all registered OPNIC ParameterTables, sorted by id.

Includes synthetic single-field tables produced by standalone OPNIC parameter promotion.

classmethod iter_standalone_opnic_parameters() → List['Parameter']

Return every OPNIC Parameter that is, or was, treated as standalone.

Union of parameters still in _pending_standalone_opnic and parameters promoted into a synthetic single-field ParameterTable (_is_synthetic_standalone == True). Pending entries come first, then promoted entries in registry order.

classmethod has_quarc_module() → bool

True iff a Quarc module is currently bound to the pool.

classmethod set_quarc_module(module: Any) → None

Bind an externally-built BaseModule (or subclass) instance.

Raises RuntimeError if a module is already bound. Use reset() first if you genuinely need to swap.

classmethod quarc_module() → Any

Return the bound Quarc module, lazily creating a default QiskitQMModule if none has been bound yet.

After this method is called once with no pre-bound module, _quarc_module is set to a QiskitQMModule instance (which sweeps pre-existing OPNIC pool state during __init__) and that becomes the slot; subsequent OPNIC ParameterTable constructions emit eagerly into it.

classmethod from_quarc_module(module: Any, opnic_runtime: Any | None = None) → Dict[str, 'ParameterTable | Parameter']

Wrap every struct in module and return a parameter dict.

This method operates in two modes depending on whether module is a live quarc.BaseModule instance or a plain dict (e.g. loaded from a rl_qoc_state.json file).

—

Mode 1 — Module object (quantum / generation side)

Input is a quarc.BaseModule (or subclass) instance. _struct_handles are already populated (built by add_struct() during construction). Each handle is paired with its struct spec to create a ParameterTable with _quarc_handle=handle.

If module is also a QiskitQMModule (has parameter_specs), non-OPNIC objects are reconstructed via reconstruct_non_opnic() and merged into the result dict.

The provided module becomes the pool’s bound accumulator. Any previously- pending OPNIC ParameterTables are swept onto it.

Mode 2 — Dictionary (classical entrypoint side)

Input is a dict (the JSON loaded directly from the state file). The opnic_runtime argument must be provided.

• "_structs" key → for each struct, the live endpoint is resolved on opnic_runtime via _resolve_runtime_endpoint() (snake_case attribute first, then the raw _structs key).

• "parameter_specs" key (optional) → non-OPNIC objects reconstructed via from_spec() / from_spec().

—

1-field struct promotion rule (both modes): structs with exactly one field are returned as a standalone Parameter; the wrapper table is flagged as _is_synthetic_standalone=True so all OPNIC transport delegates through it.

Parameters:

• module – A quarc.BaseModule instance or a state dict.

• opnic_runtime – Required when module is a dict. Must expose each struct from "_structs" as a snake_case runtime attribute (with a fallback to the raw _structs key for already-snake struct names).

Returns:

A dict mapping snake-case struct name to the wrapper object (ParameterTable for multi-field structs, Parameter for 1-field structs), plus any non-OPNIC entries keyed by attr_name / name.

Raises:

• RuntimeError – If a module is already bound (Mode 1).

• ValueError – If module is a dict but opnic_runtime is not provided, or if "_structs" key is absent.

classmethod to_quarc_module(module: Any | None = None) → Any

Bind the pool slot to module (or lazily create a default QiskitQMModule) and return it.

Behaviour:

• If module is provided, behaves like set_quarc_module() — binds the slot, raising RuntimeError if a different module is already bound. Sweeping pre-existing pool state is only automatic when module is a QiskitQMModule (via QiskitQMModule._sweep_preexisting_opnic() in __init__).

• If no module is bound yet, lazily creates a default QiskitQMModule (same sweep semantics as an explicit QiskitQMModule() construction).

• Idempotent on subsequent calls — returns the same module reference.

Returns the bound module (typically QiskitQMModule).