ParameterTable

class ParameterTable(parameters_dict: Dict[str, Tuple[float | int | bool | List | ndarray, str | type | None, Literal['INPUT_STREAM', 'OPNIC', 'IO1', 'IO2'] | InputType | None, Literal['INCOMING', 'OUTGOING'] | Direction | None] | float | int | bool | List | ndarray] | List[Parameter], name: str | None = None, *, _quarc_handle: Any | None = None, _var_is_quarc_handle: bool | None = None, _is_synthetic_standalone: bool = False, _register_in_pool: bool = True)

Bases: QuaFieldTable

Map runtime parameters to QUA variables declared in a program.

Each entry stores the Python initial value and the corresponding QUA variable name. Access values with table[parameter_name] after the table has been wired into a QUA program.

Create a parameter table from a dictionary or list of parameters.

Recommended: pass a list of pre-built Parameter objects:

ParameterTable([mu, sigma], name="PolicyParams")

Dictionary shorthand: each key is a parameter name; the value is either a bare initial value (type inferred) or a tuple with up to four fields:

# (initial_value, qua_type?, input_type?, direction?)
ParameterTable({
    "theta": 0.5,                              # scalar, type inferred
    "amps": ([0.1, 0.2], "fixed"),             # explicit qua_type
    "idx": (0, int, InputType.INPUT_STREAM),   # streamed from host
    "mu": ([0.0]*2, fixed, OPNIC, INCOMING),   # OPNIC needs direction
}, name="my_table")

All parameters in one table must share the same input_type (and the same direction when input_type is OPNIC). Use add_parameters() to attach more Parameter objects before emission (declare() for OPNIC).

Parameters:

• parameters_dict – Mapping from parameter name to initial value or parameter specification, or a list of Parameter objects.

• name – Optional table name. A unique name is generated when omitted.

declare(pause_program=False, declare_stream=True) → QuaVariable | List[QuaVariable | QuaArrayVariable]

QUA Macro to declare all QUA variables associated with the parameter table. Should be called at the beginning of the QUA program. :param pause_program: Boolean indicating if the program should pause after declaring the variables. :param declare_stream: Boolean indicating if output streams should be declared for all the parameters.

declare_stream() → List[ResultStreamSource]

QUA Macro to declare all the output streams associated with the parameters in the parameter table. This macro is expected to be called at the beginning of the QUA program.

rcv(filter_function: Callable[[Parameter], bool] | None = None)

QUA Macro to load all the input values of the parameters in the parameter table. This macro is expected to work jointly with the use of push_to_opx method on the Python side. Args: filter_func: Optional function to filter the parameters to be loaded.

save_to_stream()

Save all the parameters in the parameter table to their associated output streams.

stream_processing(mode: Literal['save', 'save_all'] = 'save_all', buffering: Dict[str | Parameter, Tuple[int, ...] | int | Literal['default']] | Literal['default'] | None = 'default')

Process all the streams in the parameter table.

assign_parameters(values: Dict[str | Parameter, int | float | bool | List | ndarray | Parameter | QuaVariable])

Assign values to the parameters of the parameter table within the QUA program. Args: values: Dictionary of the form { “parameter_name”: parameter_value }. The parameter value can be either a Python value or a QuaExpressionType.

print_parameters()

Print the parameters in the parameter table.

get_type(parameter: str | int | Parameter) → Type

Get the type of a specific parameter in the parameter table (specified by name or index).

Args: parameter: Name or index (within current table) of the parameter to get the type of.

Returns: Type of the parameter in the parameter table.

get_index(parameter_name: str | Parameter) → int

Get the index of a specific parameter in the parameter table. Args: parameter_name: (Name of the) parameter to get the index of. Returns: Index of the parameter in the parameter table.

has_parameter(parameter: str | int | Parameter) → bool

Check if a parameter is in the parameter table. Args: parameter: Name, index or instance of the parameter to be checked. Returns: True if the parameter is in the table, False otherwise.

add_parameters(parameters: Parameter | List[Parameter])

Add a (list of) parameter(s) to the parameter table. The index of the parameter is automatically set to the next available index in the table. Args: parameters: (List of) Parameter(s) object(s) to be added to the current parameter table.

remove_parameter(parameter_value: str | Parameter)

Remove a parameter from the parameter table. Args: parameter_value: Name of the parameter to be removed or ParameterValue object to be removed.

add_table(parameter_table: List[ParameterTable] | ParameterTable) → None

Add a parameter table to the current table. Args: parameter_table: ParameterTable object to be merged with the current table.

property variables_dict: Dict[str, QuaVariable | QuaArrayVariable]

Dictionary of the QUA variables corresponding to the parameters in the parameter table.

property parameters_dict: Dict[str, Parameter]

Dictionary of the parameters in the parameter table.

property parameters: List[Parameter]

List of the parameter values objects in the parameter table.

Returns: List of ParameterValue objects in the parameter table.

property is_declared: bool

Boolean indicating if all the QUA variables have been declared.

property packet

Get the packet instanceassociated with the parameter table. Relevant for OPNIC parameter tables.

property struct_type

The Quarc Struct type (a class with Scalar / Array annotations) for this OPNIC table — suitable for building a matching struct elsewhere. This is not the bound handle; reach the handle via var.

Resolution order: the frozen _struct_type cached at emission (declare); else the type recovered from a bound Quarc handle (handle._struct_spec.struct, for Flow-B reconstructed tables); else — for a not-yet-emitted table — a fresh, uncached type built from the current field set. The pre-emission build is not cached because fields may still change (add_parameters / remove_parameter) until declare() finalizes them. Relevant for OPNIC tables.

property incoming_stream_id: int

Incoming stream id for this OPNIC table (Quarc incoming spec id).

property outgoing_stream_id: int

Outgoing stream id for this OPNIC table (Quarc outgoing spec id).

property direction: Direction | None

Get the direction of the parameter table. Relevant for OPNIC parameter tables. “INCOMING”: into QUA (classical/OPNIC -> OPX) “OUTGOING”: out of QUA (OPX -> classical/OPNIC) “BOTH”: bidirectional Returns: Direction of the parameter table. None if the parameter table is not an OPNIC parameter table.

push_to_opx(param_dict: Dict[str | Parameter, float | int | bool | List | ndarray] | None = None, job: RunningQmJob | JobApi | None = None, qm: QuantumMachine | None = None, verbosity: int = 1)

Client function: Push the values of the parameters to the OPX (Python side).

For OPNIC tables, each parameter field is assigned onto the bound Quarc struct handle (self._var) and QuaStructHandle.send()-equivalent is invoked. The handle is normally the OPNIC runtime endpoint (runtime.<snake_case_struct>) on the classical side.

Parameters:

• param_dict – Optional dictionary of the form {parameter_name: parameter_value}. If None, the values of the parameters are used.

• job – RunningQmJob (only needed for IO/input-stream parameters).

• qm – QuantumMachine (only needed for IO parameters).

• verbosity – Verbosity level of the pushing process.

stream_back(reset: bool = False)

QUA Macro: Stream the values of the parameters to client/server side.

This method is used as a QUA macro to send the values of the parameters to the client/server side. It is expected to work jointly with the use of fetch_from_opx method on the client side. If InputType is OPNIC, the values are sent to the external stream. Additionally, if the user has declared a client stream on top, the values are also saved to the client stream.

Parameters:

reset – Whether to reset the parameter to a 0 value (in the appropriate QUA type) after sending it to the client/server side.

fetch_from_opx(job: RunningQmJob | JobApi | None = None, fetching_index: int = 0, fetching_size: int = 1, verbosity: int = 1, time_out: int = 30)

Client function: Fetch the values of the parameters from the OPX (Client/server side). The values are returned in a dictionary of the form {parameter_name: parameter_value}.

Args: job: RunningQmJob object to fetch the values from (input stream).

qm: QuantumMachine object to fetch the values from (IO variables). verbosity: Verbosity level of the fetching process.

Returns: Dictionary of the form {parameter_name: parameter_value}.

classmethod from_qiskit(qc: QuantumCircuit, input_type: Literal['INPUT_STREAM', 'OPNIC', 'IO1', 'IO2'] | InputType | None = None, filter_function: Callable[[QiskitParameter | Var], bool] | None = None, name: str | None = None) → 'ParameterTable' | None

Create a ParameterTable object from a QuantumCircuit object (and stores it in circuit metadata). This creates a ParameterTable that jointly encapsulates both symbolic (compile-time) parameters and input real-time variables. Returns None if no parameters are found. :param qc: QuantumCircuit object to be converted to a ParameterTable object. :param input_type: Input type of the parameters in the table. :param filter_function: Optional function to filter the parameters to be included in the table. :param name: Optional name for the parameter table.

classmethod from_other_tables(tables: List[ParameterTable] | ParameterTable, name: str | None = None) → ParameterTable

Create a ParameterTable object from a list of other ParameterTable objects. Args: tables: List of ParameterTable objects to be merged into a new table.

to_spec() → Dict[str, Any]

Serialize this table to a plain dict suitable for JSON persistence.

classmethod from_spec(spec: Dict[str, Any]) → ParameterTable

Reconstruct a ParameterTable from a spec dict produced by to_spec().

Uses pool deduplication for individual Parameter objects: Parameters shared across multiple tables are automatically restored as the same Python object.

reset()

Client function: Reset the parameter table to its initial state.

reset_qua()

QUA Macro: Reset the QUA variables of the parameter table to 0 (in the appropriate QUA type).