"""Produces a generalized Pauli-X operator matrix."""

import numpy as np


def gen_pauli_x(dim: int) -> np.ndarray:
    r"""Produce a `dim`-by-`dim` gen_pauli_x matrix [@wikipediageneralizedpauli].

    Returns the gen_pauli_x matrix of dimension `dim` described in [@wikipediageneralizedpauli].
    The gen_pauli_x matrix generates the following `dim`-by-`dim` matrix:

    \[
        \Sigma_{1, d} = \begin{pmatrix}
                        0 & 0 & 0 & \ldots & 0 & 1 \\
                        1 & 0 & 0 & \ldots & 0 & 0 \\
                        0 & 1 & 0 & \ldots & 0 & 0 \\
                        0 & 0 & 1 & \ldots & 0 & 0 \\
                        \vdots & \vdots & \vdots & \ddots & \vdots & \vdots \\
                        0 & 0 & 0 & \ldots & 1 & 0
                    \end{pmatrix}
    \]

    The gen_pauli_x matrix is primarily used in the construction of the generalized
    Pauli operators.

    Examples:
        The gen_pauli_x matrix generated from \(d = 3\) yields the following matrix:

        \[
            \Sigma_{1, 3} =
            \begin{pmatrix}
                0 & 0 & 1 \\
                1 & 0 & 0 \\
                0 & 1 & 0
            \end{pmatrix}
        \]

        ```python exec="1" source="above"
        from toqito.matrices import gen_pauli_x

        print(gen_pauli_x(3))
        ```

    Args:
        dim: Dimension of the matrix.

    Returns:
        `dim`-by-`dim` gen_pauli_x matrix.

    """
    # First column of the identity matrix becomes the last column due to `shift = -1` and `axis=1`
    return np.roll(np.identity(dim), -1, axis=1)
