Decompose a matrix into a sequence of Givens rotations and

particle-hole transformations on the last fermionic mode.

The input is an $N \times 2N$ matrix $W$ with orthonormal rows. Furthermore, $W$ must have the block form

$$ W = ( W_1 \hspace{4pt} W_2 ) $$

where $W_1$ and $W_2$ satisfy

$$ W_1 W_1^\dagger + W_2 W_2^\dagger &= I $$
W_1  W_2^T + W_2  W_1^T &= 0.

Then $W$ can be decomposed as

$$ V W U^\dagger = ( 0 \hspace{6pt} D ) $$

where $V$ and $U$ are unitary matrices and $D$ is a diagonal unitary matrix. Furthermore, $U$ can be decomposed as follows:

$$ U = B G_{k} \cdots B G_3 G_2 B G_1 B, $$

where each $G_i$ is a Givens rotation, and $B$ represents swapping the $N$-th column with the $2N$-th column, which corresponds to a particle-hole transformation on the last fermionic mode. This particle-hole transformation maps $a^\dagger_N$ to $a_N$ and vice versa, while leaving the other fermionic ladder operators invariant.

The decomposition of $U$ is returned as a list of tuples of objects describing rotations and particle-hole transformations. The list looks something like [('pht', ), (G_1, ), ('pht', G_2), ... ]. The objects within a tuple are either the string 'pht', which indicates a particle-hole transformation on the last fermionic mode, or a tuple of the form $(i, j, \theta, \varphi)$, which indicates a Givens rotation of rows $i$ and $j$ by angles $\theta$ and $\varphi$.

The matrix $V^T D^*$ can also be decomposed as a sequence of Givens rotations. This decomposition is needed for a circuit that prepares an excited state.

unitary_rows(ndarray): A matrix with orthonormal rows and additional structure described above.


decomposition (list[tuple]):
    The decomposition of $U$.
left_decomposition (list[tuple]):
    The decomposition of $V^T D^*$.
diagonal (ndarray):
    A list of the nonzero entries of $D$.
left_diagonal (ndarray):
    A list of the nonzero entries left from the decomposition
    of $V^T D^*$.