QUA2DArray

class QUA2DArray(*args, **kwargs)[source][source]

Bases: Parameter

Two-dimensional view over a single flattened 1D QUA array.

QUA only supports 1D arrays at declaration time. This class packs n_rows * n_cols elements into one backing Parameter and exposes 2D indexing, row-wise assign(), and the usual Parameter streaming and host I/O helpers.

Create a 2D logical view over one flattened 1D QUA array.

Internally this is a Parameter of length n_rows * n_cols. After declare(), use 2D indexing (arr[i, j]), row proxies (arr[i][j]), and slices (arr[i, :], arr[:, j]).

Two construction patterns are supported:

  • Shape only – pass row and column counts; elements initialize to zero.

  • From initial data – pass a 2D nested list or numpy.ndarray with ndim == 2 and omit n_cols; shape is inferred from the value.

Parameters:

  • name – Parameter name (also used as the stream / OPNIC field name).

  • n_rows_or_value – Row count (int), or a 2D initial value as a nested list or numpy.ndarray.

  • n_cols – Number of columns. Required when n_rows_or_value is an int. Omit when a 2D value array is supplied.

  • qua_type – Element QUA type: int, fixed, bool, or the strings "int", "fixed", "bool". Inferred when a 2D value array is passed.

  • input_type – Optional streaming mode (InputType): INPUT_STREAM, IO1, IO2, or OPNIC. Same semantics as Parameter.

  • direction – Required when input_type is OPNIC (Direction). Ignored otherwise.

  • units – Units label (default: empty string).

Raises:

  • ValueError – If n_cols is missing for an integer row count, dimensions are not positive, or a 2D value array is ragged or not rank-2.

  • TypeError – If n_rows_or_value is not an int, 2D list, or 2D array.

Examples

Shape-only construction:

QUA2DArray("weights", 32, 8, qua_type=fixed)

From a 2D NumPy array:

QUA2DArray("bias_grid", np.zeros((4, 16)))

Inside a QUA program:

from qm.qua import program

with program():
    grid = QUA2DArray("fake_data", 50, 8, qua_type=fixed)
    grid.declare()
    grid.assign(0, [1, 0, 1, 0, 1, 0, 1, 0])
    cell = grid[0, 0]
    row = grid[0]
assign(row: QuaVariable[int] | QuaLiteral[int] | QuaBinaryOperation[int] | QuaArrayCell[int] | QuaArrayLength[int] | QuaLibFunctionOutput[int] | QuaFunctionOutput[int] | QuaBroadcast[int] | _QuaGlobalVarOperation[int] | int, col_or_vals: QuaVariable[int] | QuaLiteral[int] | QuaBinaryOperation[int] | QuaArrayCell[int] | QuaArrayLength[int] | QuaLibFunctionOutput[int] | QuaFunctionOutput[int] | QuaBroadcast[int] | _QuaGlobalVarOperation[int] | int | Sequence | QuaArrayVariable, val: QuaVariable[NumberT] | QuaLiteral[NumberT] | QuaBinaryOperation[NumberT] | QuaArrayCell[NumberT] | QuaArrayLength[NumberT] | QuaLibFunctionOutput[NumberT] | QuaFunctionOutput[NumberT] | QuaBroadcast[NumberT] | _QuaGlobalVarOperation[NumberT] | NumberT = None)[source][source]

Generalized assign: - assign(row, col, value) → one element - assign(row, [v0, v1, …]) → entire row from Python list/ndarray - assign(row, qua_array) → entire row from a QuaArray-like

This allows you to assign a single value to a specific cell, assign an entire row from a Python list or numpy array, or assign an entire row from another QUA array variable. Note that the row index is 0-based. This method overrides the default assign method to handle 2D arrays and does not propose the same handling of conditional assignment as the original QUA assign.

Parameters:

  • row – Row index (0-based).

  • col_or_vals – Column index (0-based) or sequence of values for a full row assignment.

  • val – Value to assign when col_or_vals is a column index.

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

Stream processing for the 2D array. - mode: “save” to save only the last row, “save_all” to save all rows. - buffer: size of the buffer to use for streaming.

push_to_opx(value: ndarray | List[List[Number]], job: RunningQmJob | JobApi | None = None, qm: QuantumMachine | None = None, verbosity: int = 1, time_out: int = 30)[source][source]

Push a 2D array of values into the OPX at runtime.

value must have shape (n_rows, n_cols) (NumPy array or nested list). It is flattened in row-major order and forwarded to Parameter.push_to_opx().

The job / qm arguments match the base Parameter API: pass a RunningQmJob or JobApi. Current QUA drives IO through the job interface; qm is kept only for older call sites.

Parameters:

  • value – 2D numpy array or list-of-lists with shape (n_rows, n_cols).

  • job – Running job or job API handle used for input-stream / IO pushes. Optional; required when input_type needs a live job.

  • qm – Optional QuantumMachine. Unused with modern JobApi IO (legacy back-compat when an older job object still routed IO via the machine).

  • verbosity – Verbosity level forwarded to Parameter.push_to_opx().

  • time_out – Timeout in seconds forwarded to Parameter.push_to_opx().

Raises:

  • TypeError – value is not a numpy array or list.

  • ValueError – value is not 2D or does not match (n_rows, n_cols).