symop.polynomial.channels.unitaries.blockdiag

Helpers for assembling mode-space unitary matrices.

Includes block-diagonal composition and embedding of local k×k unitaries into a larger identity acting on multiple modes.

Functions

block_diag(*blocks)	Return the block-diagonal concatenation of multiple square matrices.
embed_1(*, n, i, u1)	Embed a 1x1 unitary into an n-dimensional identity.
embed_2(*, n, i, j, U2)	Embed a 2x2 unitary U2 acting on indices (i, j) into an n-dimensional identity.
embed_u(*, n, indices, Uk[, check_unitary, atol])	Embed a kxk unitary Uk onto a subset of indices inside an n-dimensional identity.

block_diag(*blocks: ndarray) → ndarray

Return the block-diagonal concatenation of multiple square matrices.

If blocks are U1, U2, …, then:

\[U = \mathrm{diag}(U_1, U_2, \ldots).\]

Parameters:

blocks (ndarray) – Square matrices.

Returns:

Block-diagonal matrix.

Return type:

ndarray

Raises:

ValueError – If any block is not square.

embed_1(*, n: int, i: int, u1: complex) → ndarray

Embed a 1x1 unitary into an n-dimensional identity.

\[U = I, \quad U_{i i} \leftarrow u_1.\]

Parameters:

• n (int) – Total dimension.

• i (int) – Index to replace (0-based).

• u1 (complex) – Complex scalar of modulus 1 (not enforced here).

Returns:

Matrix of shape (n, n).

Return type:

ndarray

embed_2(*, n: int, i: int, j: int, U2: ndarray) → ndarray

Embed a 2x2 unitary U2 acting on indices (i, j) into an n-dimensional identity.

The embedding acts on the subspace spanned by basis vectors i and j, leaving all other basis vectors unchanged.

Parameters:

• n (int) – Total dimension.

• i (int) – Indices to couple (0-based, distinct).

• j (int) – Indices to couple (0-based, distinct).

• U2 (ndarray) – 2x2 matrix.

Returns:

Matrix of shape (n, n).

Return type:

ndarray

embed_u(*, n: int, indices: list[int] | tuple[int, ...], Uk: ndarray, check_unitary: bool = False, atol: float = 1e-10) → ndarray

Embed a kxk unitary Uk onto a subset of indices inside an n-dimensional identity.

Parameters:

• n (int) – Total dimension.

• indices (list[int] | tuple[int, ...]) – Distinct indices (0-based) where Uk acts, in the order matching Uk.

• Uk (ndarray) – Square matrix of shape (k, k).

• check_unitary (bool) – If True, validate Uk is unitary.

• atol (float) – Tolerance for optional unitary check.

Returns:

Matrix of shape (n, n).

Return type:

ndarray

Raises:

ValueError – If indices are invalid or Uk shape mismatches.