Parameter

class Parameter(name: str, value: int | float | List | ndarray | None = None, qua_type: str | type | None = None, input_type: Literal['INPUT_STREAM', 'OPNIC', 'IO1', 'IO2'] | InputType | None = None, direction: Literal['INCOMING', 'OUTGOING', 'BOTH'] | Direction | None = None, units: str = '')

Bases: object

Class enabling the mapping of a parameter to a QUA variable to be updated. The type of the QUA variable to be adjusted can be declared explicitly or either be automatically inferred from the type of provided initial value.

Initialize a streamed or compile-time QUA parameter.

Parameters:

• name – Name of the parameter.

• value – Initial value of the parameter.

• qua_type – Type of the QUA variable to be declared (int, fixed, bool). If none is provided, the type is inferred from initial value.

• input_type – Input type of the parameter (OPNIC, INPUT_STREAM, IO1, IO2). Default is None.

• direction – Direction of the parameter stream (INCOMING, OUTGOING, BOTH). Direction is from the QUA program’s perspective (aligned with Quarc): into QUA (classical/OPNIC -> OPX): INCOMING; out of QUA (OPX -> OPNIC): OUTGOING; bidirectional: BOTH. Default is None. Relevant only when input_type is OPNIC.

• units – Units of the parameter. Default is “”.

get_index(param_table: ParameterTable) → int

Get the index of the parameter in the parameter table. :param param_table: ParameterTable object to get the index from.

Returns:

Index of the parameter in the parameter table.

Return type:

int

set_index(param_table: ParameterTable, index: int)

Set the index of the parameter in the parameter table.

Parameters:

• param_table – ParameterTable object to attach to.

• index – Index of the parameter in the parameter table.

For OPNIC parameters, attaching to a regular (non-synthetic) ParameterTable also clears the parameter from ParameterPool._pending_standalone_opnic, so the parameter is no longer a standalone candidate. Attempting to attach an already-promoted standalone parameter (whose main_table is a synthetic single-field table) to a different ParameterTable raises.

is_standalone() → bool

Backward-compat alias for is_stand_alone.

property is_stand_alone: bool

Whether this parameter is treated as a standalone OPNIC field.

A parameter is “standalone” if any of:

• it has no owning ParameterTable (still pending — has not been attached and has not been promoted yet); or

• it has been promoted into a synthetic single-field ParameterTable (_is_synthetic_standalone == True).

Once attached to a regular multi-or-single-field ParameterTable, the parameter is not standalone anymore.

property opnic_table

The synthetic single-field ParameterTable wrapping this parameter, or None if the parameter has not been promoted yet (still pending) or is part of a regular multi-field table.

property main_table: ParameterTable | None

Returns:

The ParameterTable object used to declare the parameter. Specifically, the one that should be used for communication if InputType is OPNIC.

Returns:

ParameterTable object or None if not found.

assign(value: 'Parameter' | ScalarOfAnyType | VectorOfAnyType, condition=None, value_cond: 'Parameter' | ScalarOfAnyType | VectorOfAnyType | None = None)

Assign value to the QUA variable corresponding to the parameter.

Parameters:

• value – Value to be assigned to the QUA variable. If the ParameterValue corresponds to a QUA array, the value should be a list or a QUA array of the same length.

• condition – Condition to be met for the value to be assigned to the QUA variable.

• value_cond – Optional value to be assigned to the QUA variable if provided condition is not met.

Raises:

ValueError – If the variable is not declared, or if the condition and value_cond are not provided together, or if the value_cond is not of the same type as value, or if the value length does not match the parameter length, or if the input is invalid.

declare(pause_program=False, declare_stream=True)

Declare the QUA variable associated with the parameter.

Parameters:

• pause_program – If True, pause the program after declaring the variable.

• declare_stream – If True, declare an output stream for the QUA variable.

declare_stream()

Declare the output stream associated with the parameter.

property is_declared

Whether the QUA variable is declared and still valid in the active scope.

Declaration is bound to the program scope it was made in: a fresh with program(): (a different scope token) auto-invalidates a prior declaration, so the same Parameter object can be re-declared across programs without a manual reset. Outside any program scope this is False (the token is None) — note this is a transient QUA-side concept; client-side methods (push_to_opx / fetch_from_opx) do not gate on it.

property name

Name of the parameter.

property direction

Direction of the parameter stream (INCOMING, OUTGOING, BOTH), from the QUA program’s perspective (aligned with Quarc): into QUA (classical/OPNIC -> OPX): INCOMING out of QUA (OPX -> classical/OPNIC): OUTGOING bidirectional: BOTH Default is None. Relevant only if input_type is OPNIC.

property struct_type

The Quarc Struct type of the OPNIC table that owns this parameter.

This is the typed struct definition (a class with Scalar / Array annotations) — suitable for building a matching struct elsewhere — not the bound handle. The handle is reachable via the owning table’s var. Delegates to ParameterTable.struct_type.

Raises RuntimeError if the parameter is OPNIC but not yet bound to a ParameterTable (attach it to a table, or declare it in a program to promote it as a standalone).

property var_is_quarc_handle: bool

Whether the owning OPNIC table’s transport _var is a QuaStructHandle.

True for in-process generation / Mode 1 reconstruction (QUA declare binds against initialize_in_qua). False for Mode 2 classical runtime endpoints (field accessors + send / recv only) and for non-OPNIC input types.

property incoming_stream_id: int

Incoming Quarc stream id exposed by the owning OPNIC table.

property outgoing_stream_id: int

Outgoing Quarc stream id exposed by the owning OPNIC table.

property var: QuaArrayVariable | QuaScalar

Returns: QUA variable associated with the parameter.

property tables: List[ParameterTable]

Returns: List of ParameterTable objects associated with the parameter.

property type

Type of the associated QUA variable.

property length

Length of the parameter if it refers to a QUA array ( returns 0 if single value).

property input_type: InputType | None

Type of input stream associated with the parameter.

property is_array

Boolean indicating if the parameter refers to a QUA array.

property stream: ResultStreamSource

Output stream associated with the parameter.

save_to_stream(reset: bool = False)

Save the QUA variable to the output stream.

Parameters:

reset – Whether to reset the parameter to a 0 value (in the appropriate QUA type) after saving it to the stream.

Raises:

ValueError – If the output stream is not declared, or if the variable is not declared.

stream_processing(mode: Literal['save', 'save_all'] = 'save_all', buffer: Tuple[int, ...] | int | Literal['default'] | None = 'default')

Process the output stream associated with the parameter.

Parameters:

• mode – Mode of processing the stream. Can be "save" or "save_all". Default is "save_all".

• buffer – Buffer size for the stream. Use "default" for automatic sizing, or None for no buffer.

clip(min_val: Scalar[int] | Scalar[float] | Vector[int] | Vector[float] | None = None, max_val: Scalar[int] | Scalar[float] | Vector[int] | Vector[float] | None = None, is_qua_array: bool = False)

Clip the QUA variable to a given range.

Parameters:

• min_val – Minimum value of the range.

• max_val – Maximum value of the range.

• is_qua_array – If True, treat bounds as QUA arrays.

rcv()

QUA Macro: Load a value from the input mechanism associated with the parameter. This should be corresponding to one call of the fetch_from_opx method on the client side. For input streams, the stream is advanced. For IO1 and IO2, the value is assigned to the QUA variable. For OPNIC, the value is polled.

assign_from_io(io_index: Literal[1, 2])

QUA Macro: eagerly assign the value of a global IO register into this parameter’s QUA variable, without any pause().

Unlike rcv() for IO1/IO2 (which pauses the program so a client-side push_to_opx can synchronize), this is a non-blocking, fire-and-forget read of the global IO register: the OPX keeps running. It is the correct primitive for program-level control flags whose value the server writes on the running job via qm.set_io_values(...) (a global operation that is intentionally not tied to any single parameter).

Because IO registers are scalar and global, this is only valid for a single declared scalar variable (it raises for array-backed parameters).

Parameters:

io_index – Which global IO register to read — 1 for IO1, 2 for IO2.

push_to_opx(value: int | float | bool | Sequence[int | float | bool] = <object object>, job: RunningQmJob | JobApi | None = None, qm: QuantumMachine | None = None, verbosity: int = 1, time_out: int = 30)

Client function: pass an input value to the OPX from client/server side. This should be corresponding to one call of the rcv / load_input_value method on the QUA side.

When called with no positional value argument, the stored self.value (Python-side float) is used — so you can set param.value = x once and then call param.push_to_opx() without repeating the value.

Parameters:

• value – Value to be passed to the OPX. Defaults to self.value when omitted.

• job – RunningQmJob object (required if input_type is IO1 or IO2 or input_stream).

• qm – QuantumMachine object (required if input_type is IO1 or IO2).

• verbosity – Verbosity level. Default is 1.

• time_out – Time out for waiting for the job to be paused. Default is 90 seconds.

stream_back(reset: bool = False)

QUA Macro: Save/stream the value of the parameter to the client/server side. This method uses stream_processing to save the value to the stream if input_type is not OPNIC. If input_type is OPNIC, the value is sent to the external 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=30)

Fetch a parameter value from the OPX after execution.

This method handles various input types defined by the InputType enumeration (IO1, IO2, INPUT_STREAM, OPNIC). It manages the fetching logic, including waiting for paused jobs, accessing specified result streams, and interacting with external modules when necessary. For OPNIC it also checks configurations and fetches data based on parameters related to outgoing or incoming streams.

Parameters:

• job – Running job whose result handles expose the parameter stream.

• fetching_index – Starting index when fetching a slice of values.

• fetching_size – Number of values to fetch.

• verbosity – Logging verbosity; values above 1 enable detailed output.

• time_out – Seconds to wait for the job to pause before fetching.

Returns:

Fetched value, depending on the parameter input type.

reset()

Client function: reset transient QUA-side declaration state.

Clears _is_declared, _var, _stream, _ctr. For OPNIC parameters, deliberately preserves _main_table (the owning ParameterTable, real or synthetic) so the binding to module/runtime transport survives across resets.

reset_qua()

QUA Macro: Assign the QUA variable to 0 (in the appropriate QUA type).

to_spec() → Dict[str, Any]

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

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

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

Uses pool deduplication: if a Parameter with the same name already exists in the pool (e.g. shared across multiple tables), the existing instance is returned automatically via __new__.