function a = involutory_random_matrix ( n, rank, key )

%*****************************************************************************80
%
%% involutory_random_matrix returns the INVOLUTORY_RANDOM matrix.
%
%  Example:
%
%    N = 5, RANK = 4, KEY = 123456789
%
%   -0.3830    0.0175   -0.7432    0.2818    0.4704
%    0.0175   -0.9995   -0.0211    0.0080    0.0133
%   -0.7432   -0.0211   -0.1049   -0.3395   -0.5666
%    0.2818    0.0080   -0.3395   -0.8713    0.2149
%    0.4704    0.0133   -0.5666    0.2149   -0.6413
%
%  Properties:
%
%    A is nonsingular.
%
%    A is involutory: A * A = I
%
%    det ( A ) = +1 or -1.
%
%    A is unimodular.
%
%    A is not diagonally dominant.
%
%  Licensing:
%
%    This code is distributed under the MIT license.
%
%  Modified:
%
%    12 October 2007
%
%  Author:
%
%    John Burkardt
%
%  Reference:
%
%    Alston Householder, John Carpenter,
%    The singular values of involutory and of idempotent matrices,
%    Numerische Mathematik,
%    Volume 5, 1963, pages 234-237.
%
%  Input:
%
%    integer N, the order of A.
%
%    integer RANK, the rank of the idempotent matrix
%    used to generate A.  Setting RANK = 0 or N will yield
%    a multiple of the identity.  Intermediate values will give
%    more interesting results.
%
%    integer KEY, a positive value that selects the data.
%
%  Output:
%
%    real A(N,N), the matrix.
%
  a = idempotent_random_matrix ( n, rank, key );

  for i = 1 : n
    for j = 1 : n
      if ( i == j )
        a(i,j) = 1.0 - 2.0 * a(i,j);
      else
        a(i,j) =     - 2.0 * a(i,j);
      end
    end
  end

  return
end
