QUAArray

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

Bases: Parameter

A generic N-dimensional view over one big 1D QUA array.

The underlying QUA allocation is always 1D (QUA only supports 1D arrays natively). Multi-dimensional indexing is emulated via row-major (C-order) stride arithmetic, i.e. element [i, j, k] maps to flat index i*s0 + j*s1 + k*s2 where strides are computed from the shape at construction time.

Indices may be a mix of plain Python int (resolved at compile time) and QUA integer variables (resolved at runtime). The flat-index expression produced by _flat_index is therefore either a Python int or a QUA arithmetic expression, both of which are valid as QUA array subscripts.

Supports:

  • Full indexing: arr[i, j, k] → single QUA variable

  • Partial indexing: arr[i] → _QUAArrayView proxy

  • Slice expansion: arr[i, :] → Python list of variables / views

  • Whole-array assign: arr.assign(value)

  • Element assign: arr.assign((i, j), val) (delegates to view for partial)

Exactly one of shape or value must be provided.

Parameters:

  • name – Name of the parameter.

  • shape – Tuple of ints describing the array dimensions, e.g. (3, 4). The underlying 1D QUA array is zero-initialised.

  • value – A Python list (possibly nested) or numpy array whose shape is used as the array dimensions and whose flattened contents are used as initial values.

  • qua_type – QUA type of the elements (e.g. fixed, int, bool).

  • input_type – Input type forwarded to Parameter.

  • direction – Direction forwarded to Parameter (OPNIC only).

  • units – Units string forwarded to Parameter.

Raises:

TypeError – If neither or both of shape/value are supplied, or if their types are wrong.

assign(indices_or_val, val=None)[source][source]

Flexible element / whole-array assignment.

Calling conventions:

  • arr.assign(value) — whole-array assign. value must be a list/ndarray/QUA array accepted by Parameter.assign(). Delegates directly to the parent implementation.

  • arr.assign((i,), row_value) / arr.assign((i, j), scalar_val) — partial or full index assign. indices_or_val must be a tuple of indices (Python ints or QUA variables). For partial indices a _QUAArrayView is constructed and its assign is called. For a complete index tuple a direct qua_assign is emitted.

Note

Single-element shorthand arr.assign(i, val) is intentionally not supported — always wrap indices in a tuple to avoid ambiguity with the whole-array form.

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

Push an N-D array of values into the OPX at runtime.

value is validated against self.shape, flattened to a 1-D list in row-major order, and forwarded to Parameter.push_to_opx(). This mirrors QUA2DArray.push_to_opx() for the 2-D case, generalised to arbitrary rank.

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 – A numpy array or (possibly nested) Python list whose shape must equal self.shape.

  • 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 shape does not match self.shape.

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

Declare stream-processing for this N-D array.

The QUA stream API expects a flat stream to be buffered into a shape before saving. This method builds the correct buffer tuple and calls stream.buffer(*buffer).save[_all](name).

Buffer resolution:

  • None (default) — use self.shape as the buffer; the stream is reshaped back to the array’s natural N-D shape. Equivalent to QUA2DArray’s default of (n_rows, n_cols).

  • int (leading-dimension shorthand) — prepend the integer to self.shape, yielding (int, *self.shape). Useful when the array is streamed once per repetition and you want to accumulate that many repetitions before saving.

  • tuple — used as-is. Must be a tuple of positive ints; no further total-size validation is performed here (the QUA compiler will catch mismatches).

Parameters:

  • mode – "save" to keep only the last buffer, "save_all" to accumulate all buffers (default).

  • buffer – Buffer shape — see above.

Raises:

  • ValueError – mode is invalid or the stream has not been declared.

  • TypeError – buffer is not None, an int, or a tuple.