Decompose a matrix into a sequence of Givens rotations and

particle-hole transformations on the last fermionic mode.

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

.. math::

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

where :math:W_1 and :math:W_2 satisfy

.. math::

W_1  W_1^\dagger + W_2  W_2^\dagger &= I

W_1  W_2^T + W_2  W_1^T &= 0.

Then :math:W can be decomposed as

.. math::

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

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

.. math::

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

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

The decomposition of :math: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 :math:(i, j, \theta, \varphi), which indicates a Givens rotation of rows :math:i and :math:j by angles :math:\theta and :math:\varphi.

The matrix :math: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 :math:`U`.
left_decomposition (list[tuple]):
    The decomposition of :math:`V^T D^*`.
diagonal (ndarray):
    A list of the nonzero entries of :math:`D`.
left_diagonal (ndarray):
    A list of the nonzero entries left from the decomposition
    of :math:`V^T D^*`.