Constructing idempotent matrices

Is there a general method for constructing an idempotent matrix if we are given the values of the diagonal entries?

The following should work "generically" (given a list of diagonal elements $d_i, i=1\ldots n$ where $\sum_{i=1}^n d_i = r$ is an integer, $1 \le r \le n-1$). Start with a diagonal matrix with $r$ $1$'s and $n-r$ $0$'s on the diagonal. First conjugate with a random matrix. Then for $k$ from 1 to $n-1$, conjugate with a matrix that differs from the identity only in position $(k,k+1)$, chosen to make the $(k,k)$ element $d_k$.

For example, suppose we want a $3 \times 3$ idempotent matrix with diagonal elements $2,1,-1$. Start with $\left(\matrix{1 & 0 & 0\cr 0 & 1 & 0\cr 0 & 0 & 0\cr}\right)$ and conjugate with $\left(\matrix{12 & -2 & 6\cr 15 & -7 & 3\cr 3 & 1 & -3\cr}\right)$ to get $M_0 = \left(\matrix {2/3 & -1/9 & 1/3\cr -1/2 & 5/6 & 1/2\cr 1/2 & 1/6 & 1/2\cr}\right)$. The conjugate of $M_0$ by $\left(\matrix{1 & b & 0\cr 0 & 1 & 0\cr 0 & 0 & 1\cr}\right)$ has $(1,1)$ element $2/3 + b/2$, which is $2$ for $b = 8/3$. Using this, we get $M_1 = \left(\matrix{2 & 3 & -1\cr -1/2 & -1/2 & 1/2 \cr 1/2 & 3/2 & 1/2\cr}\right)$. The conjugate of $M_1$ by $\left(\matrix{1 & 0 & 0\cr 0 & 1 & b\cr 0 & 0 & 1\cr}\right)$ has $(2,2)$ element $-1/2 - 3b/2$, which is $1$ for $b = -1$. Using this, we obtain $M_2 = \left( \matrix{2 & 3 & -4\cr 0 & 1 & 0\cr 1/2 & 3/2 & -1\cr} \right)$, which satisfies the requirements.

If $X$ is idempotent, $X^2=X$, and so by the Cayley-Hamilton theorem, the only eigenvalues are $0$ and $1$. Therefore, if you are looking at diagonal or upper triangular matrices, there are severe restrictions on what is possible.

Furthermore, if one puts an idempotent matrix in Jordan normal form, the Jordan blocks must all be of size $1$, and so $X$ must be diagonalizable. This allows a classification of idempotent matrices up to conjugation. You can thus generate idempotents by starting from a diagonal matrix with $0$'s and $1$'s and conjugating.

I am unaware of any good way to build a matrix with specified diagonal entries and eigenvalues if it is not either upper or lower triangular. However, there are definitely restrictions that can be placed on the diagonal entries. For example, because trace is conjugation invariant, we must have that if $X$ is an $n\times n$ matrix, then $0\leq \operatorname{tr} X\leq n$, and $\operatorname{tr} X \in \mathbb{N}$. The trace must also be equal to the rank of $X$.

For an invertible matrix to be idempotent, it must be conjugate to the identity matrix, and thus itself must be the identity matrix. In the $2\times 2$ case, if $X$ is idempotent but not the identity matrix or the zero matrix, then it has eigenvalues $0$ and $1$, each with multiplicity $1$. However, this condition alone ensures that the matrix can be diagonalized, and hence is idempotent. Therefore, the matrix must be of the form $$\pmatrix{a & b \\ \frac{a(1-a)}{b} & 1-a}$$.

Unfortunately, in more than $2$ dimensions, at least one of the eigenvalue multiplicities will be greater than $1$, and so the idempotentness cannot be checked by the characteristic equation alone, although it will follow from the spectral theorem if the matrix is real and symmetric.